feat: sidebar folders with rules, auto-file, and drag and drop for users and agents

apps/desktop/src/settings/DesktopClientSettings.test.ts

@@ -68,6 +68,7 @@ const clientSettings: ClientSettings = {
   threadDetailsItems: {},
   legacySidebarEnabled: false,
   sidebarWorkingShelfEnabled: false,
+  sidebarThreadFolderStyle: "tabs",
   loadBalancingEnabled: false,
   loadBalancingWeights: { "environment-1": 75, "environment-2": 0 },
   pullRequestMergeMethodOverrides: {},

apps/mobile/src/components/ui/AppSymbol.tsx

@@ -134,6 +134,12 @@ import IconWifi from "@tabler/icons-react-native/IconWifi";
 import IconWifiOff from "@tabler/icons-react-native/IconWifiOff";
 import IconWorld from "@tabler/icons-react-native/IconWorld";
 import IconX from "@tabler/icons-react-native/IconX";
+import IconBug from "@tabler/icons-react-native/IconBug";
+import IconFlask from "@tabler/icons-react-native/IconFlask";
+import IconRocket from "@tabler/icons-react-native/IconRocket";
+import IconBulb from "@tabler/icons-react-native/IconBulb";
+import IconShieldCheck from "@tabler/icons-react-native/IconShieldCheck";
+import IconGauge from "@tabler/icons-react-native/IconGauge";
 import type { AndroidSymbol, SFSymbol, SymbolViewProps } from "expo-symbols";
 import { withUniwind } from "uniwind";
 
@@ -250,6 +256,13 @@ const ANDROID_ICON_BY_SF_SYMBOL = {
   "point.topleft.down.curvedto.point.bottomright.up": IconGitMerge,
   safari: IconExternalLink,
   "server.rack": IconServer,
+  ladybug: IconBug,
+  flask: IconFlask,
+  paperplane: IconRocket,
+  lightbulb: IconBulb,
+  "checkmark.shield": IconShieldCheck,
+  cylinder: IconDatabase,
+  "gauge.with.dots.needle.33percent": IconGauge,
   stethoscope: IconStethoscope,
   "sidebar.left": IconLayoutSidebar,
   "sidebar.right": IconLayoutSidebarRight,

apps/mobile/src/features/home/HomeRouteScreen.tsx

@@ -87,6 +87,14 @@ export function HomeRouteScreen() {
   };
 
   const {
+    moveThreadToFolder,
+    createFolder,
+    renameFolder,
+    deleteFolder,
+    moveFolder,
+    setFolderCollect,
+    applyFolderRule,
+    settleFolder,
     archiveThread,
     confirmDeleteThread,
     settleThread,
@@ -242,6 +250,14 @@ export function HomeRouteScreen() {
           onPinThread={pinThread}
           onUnpinThread={unpinThread}
           onSetThreadAutoSettle={setThreadAutoSettle}
+          onMoveThreadToFolder={moveThreadToFolder}
+          onCreateFolder={createFolder}
+          onMoveFolder={moveFolder}
+          onFolderCollect={setFolderCollect}
+          onApplyFolderRule={applyFolderRule}
+          onSettleFolder={settleFolder}
+          onRenameFolder={renameFolder}
+          onDeleteFolder={deleteFolder}
           onMoveThread={moveThread}
           onRenameThread={renameThread}
           onRegenerateThreadTitle={regenerateThreadTitle}

apps/mobile/src/features/home/HomeScreen.tsx

@@ -1,3 +1,4 @@
+import type { useThreadListActions } from "./useThreadListActions";
 import { useActiveNewTask } from "../../state/active-new-task";
 import { AppActivityIndicator } from "../../components/ui/AppActivityIndicator";
 import { useAndroidControlSizing } from "../../components/ui/useAndroidControlSizing";
@@ -63,6 +64,7 @@ import {
   ThreadListV2ShowMoreRow,
   ThreadListV2SnoozedShelfHeader,
   ThreadListV2WorkingShelfHeader,
+  ThreadListV2FolderHeader,
 } from "../threads/thread-list-v2-items";
 import { useThreadRowProviderInstanceResolver } from "../threads/thread-provider-instance";
 import { useOpenThreadPullRequests } from "../threads/use-open-thread-pull-requests";
@@ -122,6 +124,14 @@ interface HomeScreenProps {
     thread: EnvironmentThreadShell,
     enabled: boolean,
   ) => Promise<boolean>;
+  readonly onMoveThreadToFolder: ReturnType<typeof useThreadListActions>["moveThreadToFolder"];
+  readonly onCreateFolder: ReturnType<typeof useThreadListActions>["createFolder"];
+  readonly onRenameFolder: ReturnType<typeof useThreadListActions>["renameFolder"];
+  readonly onDeleteFolder: ReturnType<typeof useThreadListActions>["deleteFolder"];
+  readonly onMoveFolder: ReturnType<typeof useThreadListActions>["moveFolder"];
+  readonly onFolderCollect: ReturnType<typeof useThreadListActions>["setFolderCollect"];
+  readonly onApplyFolderRule: ReturnType<typeof useThreadListActions>["applyFolderRule"];
+  readonly onSettleFolder: ReturnType<typeof useThreadListActions>["settleFolder"];
   readonly onMoveThread: (
     thread: EnvironmentThreadShell,
     direction: ThreadMoveDestination,
@@ -416,6 +426,8 @@ export function HomeScreen(props: HomeScreenProps) {
   const showMoreSettled = () =>
     setSettledVisibleCount((count) => count + THREAD_LIST_V2_SETTLED_PAGE_COUNT);
   const {
+    collapsedFolders,
+    toggleFolder,
     loaded: shelfPreferencesLoaded,
     settledShelfExpanded,
     snoozedShelfExpanded,
@@ -437,16 +449,19 @@ export function HomeScreen(props: HomeScreenProps) {
     autoSettleOptOutEnvironmentIds,
     pinReorderEnvironmentIds,
     activeReorderEnvironmentIds,
+    threadFolderEnvironmentIds,
     titleRegenerationEnvironmentIds,
   } = listEnvironments;
   const resolveProviderInstance = useThreadRowProviderInstanceResolver(providersByEnvironmentId);
   const pendingOrder = usePendingThreadOrder();
   const {
+    folders,
     layout: threadListV2Layout,
     items: threadListV2Items,
     contentOnlyThreadKeys,
     olderSettledShelf,
   } = useThreadListV2({
+    collapsedFolders,
     threads: props.threads,
     pendingTasks: props.pendingTasks,
     environmentId: props.selectedEnvironmentId,
@@ -526,6 +541,25 @@ export function HomeScreen(props: HomeScreenProps) {
         />
       );
     }
+    if (item.type === "v2-folder-header") {
+      return (
+        <ThreadListV2FolderHeader
+          item={item}
+          onToggle={toggleFolder}
+          onMove={props.onMoveFolder}
+          onCollect={props.onFolderCollect}
+          onApplyRule={props.onApplyFolderRule}
+          onSettle={props.onSettleFolder}
+          onRename={props.onRenameFolder}
+          onDelete={props.onDeleteFolder}
+          environmentLabel={
+            Object.keys(props.savedConnectionsById).length > 1
+              ? props.savedConnectionsById[item.environmentId]?.environmentLabel
+              : null
+          }
+        />
+      );
+    }
     if (item.type === "v2-working-shelf") {
       return (
         <ThreadListV2WorkingShelfHeader
@@ -606,10 +640,15 @@ export function HomeScreen(props: HomeScreenProps) {
         snoozePresets={snoozePresetsByEnvironmentId.get(thread.environmentId)}
         pinningSupported={pinningEnvironmentIds.has(thread.environmentId)}
         autoSettleOptOutSupported={autoSettleOptOutEnvironmentIds.has(thread.environmentId)}
+        folders={folders}
+        foldersSupported={threadFolderEnvironmentIds.has(thread.environmentId)}
+        onMoveThreadToFolder={props.onMoveThreadToFolder}
+        onCreateFolder={props.onCreateFolder}
         reorderSupported={
-          item.item.pinned
+          !item.item.folderKey &&
+          (item.item.pinned
             ? pinReorderEnvironmentIds.has(thread.environmentId)
-            : !workingShelfEnabled && activeReorderEnvironmentIds.has(thread.environmentId)
+            : !workingShelfEnabled && activeReorderEnvironmentIds.has(thread.environmentId))
         }
         canMoveUp={item.canMoveUp}
         canMoveDown={item.canMoveDown}
@@ -631,6 +670,7 @@ export function HomeScreen(props: HomeScreenProps) {
 
   // extraData changes invalidate every visible row; put the minute clock on items to limit updates.
   const v2ExtraData = {
+    folders,
     activeNewTask,
     projectByKey,
     projectTitleByProjectKey: v2ProjectTitleByProjectKey,
@@ -643,6 +683,7 @@ export function HomeScreen(props: HomeScreenProps) {
   };
 
   const hasAnyThreads =
+    threadListV2Layout.folderHeaders.length > 0 ||
     props.threads.some((thread) => thread.archivedAt === null) ||
     props.pendingTasks.length > 0 ||
     threadListV2Layout.settledCount > 0;

apps/mobile/src/features/home/useThreadListActions.test.ts

@@ -1,3 +1,4 @@
+import type { EnvironmentThreadFolder } from "@t3tools/client-runtime/state/thread-folders";
 import { makeThreadShellFixture } from "../../test-fixtures";
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
 import {
@@ -7,6 +8,8 @@ import {
   ProviderInstanceId,
   RunId,
   ThreadId,
+  ThreadFolderId,
+  type ThreadFolderMutation,
 } from "@t3tools/contracts";
 import * as Cause from "effect/Cause";
 import { AsyncResult } from "effect/reactivity";
@@ -19,6 +22,8 @@ const state = vi.hoisted(() => ({
   archivedRefreshes: [] as string[],
   scopes: new Map<string, Set<string>>(),
   shells: [] as EnvironmentThreadShell[],
+  folders: [] as EnvironmentThreadFolder[],
+  folderRequests: [] as { environmentId: string; input: ThreadFolderMutation }[],
   requests: [] as {
     action: string;
     environmentId: string;
@@ -42,6 +47,7 @@ vi.mock("react-native", () => ({
       state.alerts.push({ title, buttons }),
   },
 }));
+vi.mock("expo-crypto", () => ({ randomUUID: () => "uuid" }));
 vi.mock("expo-haptics", () => ({
   impactAsync: async () => {},
   ImpactFeedbackStyle: { Light: "light" },
@@ -62,35 +68,48 @@ vi.mock("../../state/session", () => ({
 }));
 vi.mock("../../state/server", () => ({
   environmentServerConfigsAtom: "server-configs",
+  serverEnvironment: {
+    mutateThreadFolders: async (request: {
+      environmentId: string;
+      input: ThreadFolderMutation;
+    }) => {
+      state.folderRequests.push(request);
+      return AsyncResult.success(undefined);
+    },
+  },
+  threadFoldersAtom: "thread-folders",
 }));
 vi.mock("../../state/atom-registry", () => ({
   appAtomRegistry: {
     set: (_atom: string, value: boolean) => {
       state.dropBusy = value;
     },
     get: (atom: string) =>
-      atom === "thread-drop-busy"
-        ? state.dropBusy
-        : atom === "thread-shells"
-          ? state.shells
-          : atom === "queued-thread-keys"
-            ? new Set<string>()
-            : new Map(
-                [...state.scopes.keys()].map((environmentId) => [
-                  environmentId,
-                  {
-                    environment: {
-                      capabilities: {
-                        threadSettlement: true,
-                        threadSnooze: true,
-                        threadPinning: true,
-                        threadPinReorder: true,
-                        threadTitleRegeneration: true,
+      atom === "thread-folders"
+        ? state.folders
+        : atom === "thread-drop-busy"
+          ? state.dropBusy
+          : atom === "thread-shells"
+            ? state.shells
+            : atom === "queued-thread-keys"
+              ? new Set<string>()
+              : new Map(
+                  [...state.scopes.keys()].map((environmentId) => [
+                    environmentId,
+                    {
+                      environment: {
+                        capabilities: {
+                          threadFolders: true,
+                          threadSettlement: true,
+                          threadSnooze: true,
+                          threadPinning: true,
+                          threadPinReorder: true,
+                          threadTitleRegeneration: true,
+                        },
                       },
                     },
-                  },
-                ]),
-              ),
+                  ]),
+                ),
   },
 }));
 vi.mock("../../state/use-atom-command", () => ({
@@ -189,6 +208,8 @@ beforeEach(() => {
   ]);
   state.requests = [];
   state.shells = [];
+  state.folders = [];
+  state.folderRequests = [];
   state.dialogs = [];
   state.alerts = [];
   state.afterRequest = undefined;
@@ -481,3 +502,55 @@ describe("thread archive guard", () => {
     expect(state.alerts.at(-1)?.title).toBe("Could not archive thread");
   });
 });
+
+describe("folder actions", () => {
+  it("reorders only within the folder's environment and rejects moves at the ends", async () => {
+    const folder: EnvironmentThreadFolder = {
+      environmentId: primaryEnvironmentId,
+      id: ThreadFolderId.make("first"),
+      name: "First",
+      icon: null,
+      threadIds: [],
+      rule: { titleKeywords: ["test"] },
+      autoFile: false,
+      ruleSetAt: null,
+      createdAt: "2026-09-02T00:00:00.000Z",
+      updatedAt: "2026-09-02T00:00:00.000Z",
+    };
+    const second = { ...folder, id: ThreadFolderId.make("second") };
+    const third = { ...folder, id: ThreadFolderId.make("third") };
+    state.folders = [folder, { ...folder, environmentId: otherEnvironmentId }, second, third];
+    const actions = useThreadListActions();
+    const shown = [folder, second, third];
+    expect(await actions.moveFolder(folder, "up", shown)).toBe(false);
+    expect(await actions.moveFolder(third, "down", shown)).toBe(false);
+    expect(await actions.moveFolder(second, "up", shown)).toBe(true);
+    expect(await actions.moveFolder(folder, "down", shown)).toBe(true);
+    expect(await actions.moveFolder(second, "down", shown)).toBe(true);
+    expect(state.folderRequests).toEqual([
+      {
+        environmentId: primaryEnvironmentId,
+        input: { type: "folder.reorder", folderId: second.id, beforeFolderId: folder.id },
+      },
+      {
+        environmentId: primaryEnvironmentId,
+        input: { type: "folder.reorder", folderId: folder.id, beforeFolderId: third.id },
+      },
+      {
+        environmentId: primaryEnvironmentId,
+        input: { type: "folder.reorder", folderId: second.id, beforeFolderId: null },
+      },
+    ]);
+    expect(await actions.setFolderCollect(folder, { by: "topic" })).toBe(true);
+    expect(state.folderRequests.at(-1)?.input).toEqual({
+      type: "folder.update",
+      folderId: folder.id,
+      rule: { smart: true },
+      autoFile: true,
+    });
+    state.scopes.get(primaryEnvironmentId)!.clear();
+    expect(await actions.moveFolder(second, "up", shown)).toBe(false);
+    expect(await actions.setFolderCollect(folder, { by: "topic" })).toBe(false);
+    expect(state.folderRequests).toHaveLength(4);
+  });
+});