@vellumai/assistant 0.11.2-dev.202608052129.f237b1e → 0.11.2-dev.202608052227.261a826

package/openapi.yaml

@@ -6585,6 +6585,16 @@ paths:
           description:
             Filter by origin channel. When provided, only conversations with this exact origin_channel value are
             returned. Omit to include all channels.
+        - name: groupId
+          in: query
+          required: false
+          schema:
+            type: string
+          description:
+            Filter to a single group, so each sidebar section can load independently of the paginated list. Pass
+            "system:all" for conversations in no group, "system:pinned" for the Pinned section, or a custom group id. A
+            group-scoped request is ordered by the user's arrangement (display order, then recency) and never has pinned
+            rows appended to it. Omit to span every group.
       responses:
         "200":
           description: Successful response

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.2-dev.202608052129.f237b1e",
+  "version": "0.11.2-dev.202608052227.261a826",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/conversation-group-tools.test.ts

@@ -257,7 +257,7 @@ describe("conversation_move_to_group tool", () => {
     expect(result.content).toContain("no conversation found");
   });
 
-  test("notes hidden conversation types", async () => {
+  test("tells the model a custom group surfaces a hidden conversation", async () => {
     createConversation({ id: "conv-bg", conversationType: "background" });
     await executeConversationGroupCreate({ name: "Visible" }, ctx);
 
@@ -267,7 +267,37 @@ describe("conversation_move_to_group tool", () => {
     );
 
     expect(result.isError).toBe(false);
-    expect(result.content).toContain("hidden from the sidebar");
+    expect(result.content).toContain("surfaces it into the sidebar");
+  });
+
+  test("does not claim a move to Recents surfaces a hidden conversation", async () => {
+    // Recents is a removal target, not a promotion: the write path leaves an
+    // unpromoted background row hidden there, so saying otherwise would report
+    // an outcome to the model that did not happen.
+    createConversation({ id: "conv-bg-all", conversationType: "background" });
+
+    const result = await executeConversationMoveToGroup(
+      { group: "system:all", conversation_id: "conv-bg-all" },
+      ctx,
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content).not.toContain("surfaces it into the sidebar");
+  });
+
+  test("does not claim a move to Background surfaces a hidden conversation", async () => {
+    createConversation({
+      id: "conv-bg-demote",
+      conversationType: "background",
+    });
+
+    const result = await executeConversationMoveToGroup(
+      { group: "system:background", conversation_id: "conv-bg-demote" },
+      ctx,
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content).not.toContain("surfaces it into the sidebar");
   });
 
   test("rejects missing group", async () => {

package/src/__tests__/conversation-placement-promotion.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Filing a background or scheduled conversation into a section the user reads
+ * promotes it durably.
+ *
+ * Placement into Pinned or a custom group stamps `surfaced_at`, so the
+ * promotion outlives the placement that caused it: taking the conversation
+ * back out returns it to Recents rather than hiding it. Demotion is the
+ * mirror image, and filing into `system:background` / `system:scheduled`
+ * clears the stamp.
+ *
+ * The cases below pin both edges. Under-promoting hides a conversation the
+ * user deliberately filed somewhere; over-promoting drags hidden automation
+ * into the sidebar, so the "what promotion must not do" block is as
+ * load-bearing as the rest.
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  batchSetDisplayOrders,
+  createConversation,
+} from "../persistence/conversation-crud.js";
+import { listConversations } from "../persistence/conversation-queries.js";
+import { getDb } from "../persistence/db-connection.js";
+import { initializeDb } from "../persistence/db-init.js";
+import { createGroup } from "../persistence/group-crud.js";
+import { rawRun } from "../persistence/raw-query.js";
+import { conversations } from "../persistence/schema/index.js";
+
+await initializeDb();
+
+function seedRoutedBackground(title: string, type: "background" | "scheduled") {
+  const conv = createConversation({ title, conversationType: type });
+  rawRun(
+    "test:routeToSystemBucket",
+    "UPDATE conversations SET group_id = ? WHERE id = ?",
+    type === "scheduled" ? "system:scheduled" : "system:background",
+    conv.id,
+  );
+  return conv;
+}
+
+/** Titles the sidebar's standard listing would render. */
+function visibleTitles(): string[] {
+  return listConversations({ limit: 100 }).map((c) => c.title ?? "");
+}
+
+function titlesInGroup(groupId: string): string[] {
+  return listConversations({ limit: 100, groupId }).map((c) => c.title ?? "");
+}
+
+beforeEach(() => {
+  getDb().delete(conversations).run();
+});
+
+describe("pinning a background conversation", () => {
+  test("shows it in Pinned", () => {
+    const conv = seedRoutedBackground("bg-job", "background");
+    expect(visibleTitles()).toEqual([]);
+
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: 0, groupId: "system:pinned" },
+    ]);
+
+    expect(titlesInGroup("system:pinned")).toEqual(["bg-job"]);
+  });
+
+  test("unpinning lands it in Recents rather than hiding it again", () => {
+    const conv = seedRoutedBackground("bg-job", "background");
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: 0, groupId: "system:pinned" },
+    ]);
+
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: null, groupId: "system:all" },
+    ]);
+
+    expect(titlesInGroup("system:all")).toEqual(["bg-job"]);
+  });
+});
+
+describe("filing a background conversation into a custom group", () => {
+  test("shows it in that group", () => {
+    const group = createGroup("Car Chat");
+    const conv = seedRoutedBackground("bg-job", "background");
+
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: 0, groupId: group.id },
+    ]);
+
+    expect(titlesInGroup(group.id)).toEqual(["bg-job"]);
+  });
+
+  test("removing it from the group lands it in Recents rather than losing it", () => {
+    const group = createGroup("Car Chat");
+    const conv = seedRoutedBackground("bg-job", "background");
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: 0, groupId: group.id },
+    ]);
+
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: null, groupId: "system:all" },
+    ]);
+
+    expect(titlesInGroup("system:all")).toEqual(["bg-job"]);
+    expect(visibleTitles()).toEqual(["bg-job"]);
+  });
+
+  test("applies to scheduled conversations too", () => {
+    const group = createGroup("Morning Briefs");
+    const conv = seedRoutedBackground("sched-job", "scheduled");
+
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: 0, groupId: group.id },
+    ]);
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: null, groupId: "system:all" },
+    ]);
+
+    expect(titlesInGroup("system:all")).toEqual(["sched-job"]);
+  });
+});
+
+describe("what promotion must not do", () => {
+  test("filing into system:background still demotes", () => {
+    const conv = seedRoutedBackground("bg-job", "background");
+    // Promote first, so the demotion has something to undo.
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: 0, groupId: "system:pinned" },
+    ]);
+    expect(titlesInGroup("system:pinned")).toEqual(["bg-job"]);
+
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: null, groupId: "system:background" },
+    ]);
+
+    expect(visibleTitles()).toEqual([]);
+  });
+
+  test("a background conversation nobody placed anywhere stays hidden", () => {
+    seedRoutedBackground("untouched", "background");
+
+    expect(visibleTitles()).toEqual([]);
+  });
+
+  test("moving to system:all does not by itself promote", () => {
+    // Removal is not a promotion: a row that was never filed into a section
+    // the user reads must not become visible just by being moved out of its
+    // system bucket.
+    const conv = seedRoutedBackground("bg-job", "background");
+
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: null, groupId: "system:all" },
+    ]);
+
+    expect(visibleTitles()).toEqual([]);
+  });
+
+  test("unpinning through the legacy isPinned path still lands in Recents", () => {
+    // Old clients send `isPinned: false` with no `groupId`, and that branch
+    // restores the row's original system bucket to keep its provenance. It
+    // deliberately does not clear the promotion: unpinning is not a demotion,
+    // so the conversation belongs in Recents afterwards, the same as the
+    // modern path that sends `groupId: "system:all"`.
+    //
+    // The row therefore sits in `system:background` while remaining visible.
+    // That is the intended split: the bucket records where the conversation
+    // came from, `surfaced_at` records that the user promoted it, and only
+    // an explicit demotion clears the latter.
+    const conv = seedRoutedBackground("bg-job", "background");
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: 0, groupId: "system:pinned" },
+    ]);
+
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: null, isPinned: false },
+    ]);
+
+    expect(visibleTitles()).toEqual(["bg-job"]);
+    expect(titlesInGroup("system:all")).toEqual(["bg-job"]);
+  });
+
+  test("standard conversations are not stamped as surfaced", () => {
+    // They are already visible, so stamping them would leave `surfaced_at`
+    // meaning nothing.
+    const group = createGroup("Car Chat");
+    const conv = createConversation("plain-chat");
+
+    batchSetDisplayOrders([
+      { id: conv.id, displayOrder: 0, groupId: group.id },
+    ]);
+
+    const row = getDb()
+      .all(`SELECT surfaced_at FROM conversations WHERE id = '${conv.id}'`)
+      .at(0) as { surfaced_at: number | null };
+    expect(row.surfaced_at).toBeNull();
+  });
+});

package/src/__tests__/custom-group-listing-visibility.test.ts

@@ -33,7 +33,7 @@ describe("custom-group standard-listing visibility", () => {
   });
 
   function listedIds(): string[] {
-    return listConversations(undefined, "standard").map((c) => c.id);
+    return listConversations({ conversationType: "standard" }).map((c) => c.id);
   }
 
   test("scheduled conversation in a custom group is listed", () => {

package/src/cli.ts

@@ -513,7 +513,7 @@ export async function startCli(): Promise<void> {
     if (content === "/conversations") {
       pendingSessionPick = true;
       try {
-        const rows = listConversations(20);
+        const rows = listConversations({ limit: 20 });
         const conversations = rows.map((r) => ({
           id: r.id,
           title: r.title || "Untitled",

package/src/daemon/handlers/conversation-history.ts

@@ -22,7 +22,7 @@ export async function performConversationSearch(
 ) {
   // Treat "*" as a list-all wildcard — FTS treats it as a literal character.
   if (params.query.trim() === "*") {
-    const rows = listConversations(params.limit);
+    const rows = listConversations({ limit: params.limit });
     return rows.map((r) => ({
       conversationId: r.id,
       conversationTitle: r.title,

package/src/persistence/conversation-crud.ts

@@ -75,6 +75,8 @@ import {
   BACKGROUND_CONVERSATION_TYPES,
   type ConversationCreateType,
   isHiddenMessageMetadata,
+  PINNED_GROUP_ID,
+  UNGROUPED_GROUP_ID,
 } from "./conversation-types.js";
 import { runAsyncSqlite } from "./db-async-query.js";
 import {
@@ -1040,7 +1042,7 @@ export function createConversation(
   // write-contended paths wrap the call in `withSqliteRetry`, and because the
   // insert+update are atomic here, such a retry re-runs the whole thing cleanly
   // (a failed attempt rolls back, so no half-written row is ever left behind).
-  const effectiveGroupId = groupId ?? "system:all";
+  const effectiveGroupId = groupId ?? UNGROUPED_GROUP_ID;
   const raw = getSqliteFrom(db);
   raw.exec("SAVEPOINT create_conv");
   try {
@@ -1049,7 +1051,7 @@ export function createConversation(
       "conversation:create:setGroup",
       "UPDATE conversations SET group_id = ?, is_pinned = ? WHERE id = ?",
       effectiveGroupId,
-      effectiveGroupId === "system:pinned" ? 1 : 0,
+      effectiveGroupId === PINNED_GROUP_ID ? 1 : 0,
       id,
     );
     raw.exec("RELEASE create_conv");
@@ -4031,7 +4033,7 @@ export function batchSetDisplayOrders(
         // the entire batch.
         let safeGroupId = update.groupId;
         if (safeGroupId === null) {
-          safeGroupId = "system:all";
+          safeGroupId = UNGROUPED_GROUP_ID;
         } else if (
           !rawGet<{ id: string }>(
             "conversation:batchSetDisplayOrders:groupCheck",
@@ -4039,7 +4041,7 @@ export function batchSetDisplayOrders(
             safeGroupId,
           )
         ) {
-          safeGroupId = "system:all";
+          safeGroupId = UNGROUPED_GROUP_ID;
         }
         // Moving a conversation into the Scheduled/Background system groups
         // is an explicit demotion out of Recents, so clear any `surfaced_at`
@@ -4049,15 +4051,49 @@ export function batchSetDisplayOrders(
         const clearsSurfaced =
           safeGroupId === "system:background" ||
           safeGroupId === "system:scheduled";
-        rawRun(
-          "conversation:batchSetDisplayOrders:group",
-          `UPDATE conversations SET display_order = ?, is_pinned = ?, group_id = ?${
-            clearsSurfaced ? ", surfaced_at = NULL" : ""
-          } WHERE id = ?`,
+        // Filing a conversation into a section the user reads (Pinned or one
+        // of their own groups) is the mirror image: an explicit promotion, so
+        // it stamps `surfaced_at` the way the surface API does.
+        //
+        // The stamp is what makes the promotion durable. Visibility must not
+        // depend on where the row currently sits, or removing it from a group
+        // would hide it instead of returning it to Recents, and pinning would
+        // not show it at all: `system:pinned` fails the custom-group arm of
+        // `standardListingVisibilitySql` on that arm's `system:` prefix check.
+        //
+        // Only background and scheduled rows need it: everything else is
+        // already visible, and stamping them would leave `surfaced_at`
+        // meaning nothing. `COALESCE` keeps the original promotion time when
+        // the row is re-filed later.
+        const promotes =
+          !clearsSurfaced &&
+          safeGroupId !== UNGROUPED_GROUP_ID &&
+          (safeGroupId === PINNED_GROUP_ID ||
+            !safeGroupId.startsWith("system:"));
+        const setClauses = [
+          "display_order = ?",
+          "is_pinned = ?",
+          "group_id = ?",
+        ];
+        const params: Array<string | number | null> = [
           update.displayOrder,
-          safeGroupId === "system:pinned" ? 1 : 0,
+          safeGroupId === PINNED_GROUP_ID ? 1 : 0,
           safeGroupId,
-          update.id,
+        ];
+        if (clearsSurfaced) {
+          setClauses.push("surfaced_at = NULL");
+        } else if (promotes) {
+          setClauses.push(
+            "surfaced_at = CASE WHEN conversation_type IN ('background', 'scheduled')" +
+              " THEN COALESCE(surfaced_at, ?) ELSE surfaced_at END",
+          );
+          params.push(Date.now());
+        }
+        params.push(update.id);
+        rawRun(
+          "conversation:batchSetDisplayOrders:group",
+          `UPDATE conversations SET ${setClauses.join(", ")} WHERE id = ?`,
+          ...params,
         );
       } else if (update.isPinned === undefined) {
         // Only displayOrder provided — preserve existing pin state and group.

package/src/persistence/conversation-plugin-facade.ts

@@ -136,7 +136,13 @@ export async function deleteConversation(id: string): Promise<void> {
   }
 }
 
-/** List conversation rows, newest first. */
+/**
+ * List conversation rows, newest first.
+ *
+ * The positional signature is part of the plugin API surface and stays
+ * stable; the underlying query takes a named filter, which this maps onto.
+ * Omitted arguments stay omitted so the query's own defaults apply.
+ */
 export async function listConversations(
   limit?: number,
   conversationType?: ConversationType,
@@ -145,8 +151,13 @@ export async function listConversations(
   originChannel?: string,
 ): Promise<ConversationRow[]> {
   const { listConversations: fn } = await import("./conversation-queries.js");
-  // Explicit `undefined` arguments fall through to the underlying defaults.
-  return fn(limit, conversationType, offset, archiveStatus, originChannel);
+  return fn({
+    ...(limit !== undefined ? { limit } : {}),
+    ...(conversationType !== undefined ? { conversationType } : {}),
+    ...(offset !== undefined ? { offset } : {}),
+    ...(archiveStatus !== undefined ? { archiveStatus } : {}),
+    ...(originChannel !== undefined ? { originChannel } : {}),
+  });
 }
 
 /** Sparse lexical search over stored message text; ranked message-id hits. */

package/src/persistence/conversation-queries.ts

@@ -14,7 +14,11 @@ import { parseConversation } from "./conversation-crud.js";
 import { ensureDisplayOrderMigration } from "./conversation-display-order-migration.js";
 import { ensureGroupMigration } from "./conversation-group-migration.js";
 import { searchMessageIdsLexical } from "./conversation-search-lexical.js";
-import type { ConversationType } from "./conversation-types.js";
+import {
+  type ConversationType,
+  PINNED_GROUP_ID,
+  UNGROUPED_GROUP_ID,
+} from "./conversation-types.js";
 import { getDb } from "./db-connection.js";
 import { tokenize } from "./embeddings/sparse-tokenize.js";
 import {
@@ -236,34 +240,132 @@ function conversationTypeClause(type: ConversationType) {
   }
 }
 
+/**
+ * The predicates that select which conversations a listing covers, shared by
+ * {@link listConversations} and {@link countConversations} so a list and its
+ * count can never disagree about what they are describing.
+ *
+ * Named rather than positional on purpose: `originChannel` and `groupId` are
+ * both optional strings, and as adjacent positional arguments they were a
+ * transposition waiting to happen.
+ */
+export interface ConversationListFilter {
+  conversationType?: ConversationType;
+  archiveStatus?: ArchiveStatusFilter;
+  originChannel?: string;
+  /**
+   * Restrict to one group. {@link UNGROUPED_GROUP_ID} selects rows in no
+   * group (the sidebar's flat list), {@link PINNED_GROUP_ID} the Pinned
+   * section, and a UUID one custom group. Omit to span every group.
+   */
+  groupId?: string;
+}
+
+export interface ConversationListQuery extends ConversationListFilter {
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * SQL predicate for {@link ConversationListFilter.groupId}.
+ *
+ * The ungrouped case has to match NULL as well as the literal sentinel:
+ * `group_id` is only written when a conversation is filed somewhere, so the
+ * overwhelming majority of rows carry NULL rather than `'system:all'`.
+ *
+ * `group_id` is referenced as raw SQL because it is not a Drizzle column:
+ * it, `display_order`, and `is_pinned` are added by the lazy
+ * `ensureDisplayOrderMigration` / `ensureGroupMigration` steps rather than
+ * declared in `schema/conversations.ts`.
+ */
+function groupIdClause(groupId: string) {
+  if (groupId === UNGROUPED_GROUP_ID) {
+    // "Ungrouped" means every row the sidebar's flat list shows: not pinned
+    // and not filed in a custom group. It deliberately admits the system
+    // buckets, because a surfaced background or scheduled conversation keeps
+    // its `system:background` / `system:scheduled` group id (surfacing writes
+    // only `surfaced_at`) while the standard listing renders it in Recents.
+    // Whether such a row is actually visible stays with
+    // `conversationTypeClause`, which admits the surfaced ones and excludes
+    // the rest; matching on group id alone here would drop them.
+    return sql`(group_id IS NULL OR (group_id LIKE 'system:%' AND group_id != ${PINNED_GROUP_ID}))`;
+  }
+  // `group_id` is single-valued and authoritative, so a row belongs to
+  // exactly one section by construction. `is_pinned` is a derived duplicate
+  // that reads do not consult: `ensureGroupMigration` backfills
+  // `group_id = 'system:pinned'` for every legacy `is_pinned` row before any
+  // query runs, and pinning writes both together thereafter.
+  return sql`group_id = ${groupId}`;
+}
+
+/**
+ * Order a group's rows the way the user arranged them: by explicit
+ * `display_order` first, then by recency. Only meaningful for a real group;
+ * the ungrouped bucket is pure recency, since a row that was dragged inside a
+ * group and later removed keeps a stale `display_order` that must not
+ * resurface as a sort key.
+ */
+function isUserOrderedGroup(groupId: string | undefined): boolean {
+  if (groupId === undefined) {
+    return false;
+  }
+  // Pinned and custom groups are the only drag-reorderable sections, so they
+  // are the only ones whose `display_order` means anything. Every other
+  // system bucket sorts by recency: `batchSetDisplayOrders` writes
+  // `display_order` alongside `group_id` when a row moves into
+  // `system:background` / `system:scheduled`, and that value persists through
+  // later moves, so honouring it would order the same section differently
+  // depending on whether it was fetched by `conversationType` or `groupId`.
+  return groupId === PINNED_GROUP_ID || !groupId.startsWith("system:");
+}
+
+function conversationListWhere(filter: ConversationListFilter) {
+  const {
+    conversationType = "standard",
+    archiveStatus = "active",
+    originChannel,
+    groupId,
+  } = filter;
+  return and(
+    conversationTypeClause(conversationType),
+    archiveStatusClause(archiveStatus) ?? undefined,
+    originChannel ? eq(conversations.originChannel, originChannel) : undefined,
+    groupId ? groupIdClause(groupId) : undefined,
+  );
+}
+
 export function listConversations(
-  limit?: number,
-  conversationType: ConversationType = "standard",
-  offset = 0,
-  archiveStatus: ArchiveStatusFilter = "active",
-  originChannel?: string,
+  query: ConversationListQuery = {},
 ): ConversationRow[] {
   ensureDisplayOrderMigration();
   ensureGroupMigration();
   const db = getDb();
-  const typeCond = conversationTypeClause(conversationType);
-  const archiveCond = archiveStatusClause(archiveStatus);
-  const channelCond = originChannel
-    ? eq(conversations.originChannel, originChannel)
-    : undefined;
-  const where = and(typeCond, archiveCond ?? undefined, channelCond);
-  const query = db
+  const { limit, offset = 0, ...filter } = query;
+  const recency = desc(
+    sql`COALESCE(${conversations.lastMessageAt}, ${conversations.updatedAt})`,
+  );
+  // `id` closes the ordering so the sort is a total order. Rows tied on every
+  // preceding key would otherwise have no defined relative order, which
+  // becomes duplicated and skipped rows once a cursor pages across a tie
+  // boundary.
+  //
+  // Deliberately untested here: SQLite returns a stable arrangement for
+  // identical queries over identical data, so no assertion at this layer can
+  // distinguish a total order from a lucky one. The guarantee becomes
+  // observable, and gets its test, with the keyset pagination work.
+  const tiebreak = desc(conversations.id);
+  const orderBy = isUserOrderedGroup(filter.groupId)
+    ? [sql`COALESCE(display_order, 999999) ASC`, recency, tiebreak]
+    : [recency, tiebreak];
+  return db
     .select()
     .from(conversations)
-    .where(where)
-    .orderBy(
-      desc(
-        sql`COALESCE(${conversations.lastMessageAt}, ${conversations.updatedAt})`,
-      ),
-    )
+    .where(conversationListWhere(filter))
+    .orderBy(...orderBy)
     .limit(limit ?? 100)
-    .offset(offset);
-  return query.all().map(parseConversation);
+    .offset(offset)
+    .all()
+    .map(parseConversation);
 }
 
 /**
@@ -447,23 +549,21 @@ export function listConversationsByTitlePrefix(
   }));
 }
 
+/**
+ * How many conversations {@link listConversations} would return for the same
+ * filter, ignoring `limit` / `offset`. Both read through
+ * {@link conversationListWhere}, so a page and its total always describe the
+ * same set.
+ */
 export function countConversations(
-  conversationType: ConversationType = "standard",
-  archiveStatus: ArchiveStatusFilter = "active",
-  originChannel?: string,
+  filter: ConversationListFilter = {},
 ): number {
   ensureGroupMigration();
   const db = getDb();
-  const typeCond = conversationTypeClause(conversationType);
-  const archiveCond = archiveStatusClause(archiveStatus);
-  const channelCond = originChannel
-    ? eq(conversations.originChannel, originChannel)
-    : undefined;
-  const where = and(typeCond, archiveCond ?? undefined, channelCond);
   const [{ total }] = db
     .select({ total: count() })
     .from(conversations)
-    .where(where)
+    .where(conversationListWhere(filter))
     .all();
   return total;
 }

package/src/persistence/conversation-types.ts

@@ -257,3 +257,13 @@ export function isReplyPushIneligibleUserMessage(
     (!options?.replyDeliveredInAppOnly && isReplyDeliveredOffApp(metadata))
   );
 }
+
+/**
+ * The reserved `group_id` values the sidebar's system sections use.
+ *
+ * `group_id` is nullable, and a conversation that has never been filed
+ * carries NULL rather than {@link UNGROUPED_GROUP_ID}, so predicates over the
+ * column read it through `COALESCE(group_id, 'system:all')`.
+ */
+export const UNGROUPED_GROUP_ID = "system:all";
+export const PINNED_GROUP_ID = "system:pinned";

package/src/plugins/defaults/memory/__tests__/conversation-queries.test.ts

@@ -396,7 +396,7 @@ describe("countConversations", () => {
     const priv = createConversation("private-1");
     setConversationType(priv.id, "private");
 
-    expect(countConversations("background")).toBe(2);
+    expect(countConversations({ conversationType: "background" })).toBe(2);
   });
 
   test("includes standard conversations with group_id system:background in background count", () => {
@@ -411,13 +411,13 @@ describe("countConversations", () => {
     createConversation("foreground-1");
 
     // WHEN counting background conversations
-    const bgCount = countConversations("background");
+    const bgCount = countConversations({ conversationType: "background" });
 
     // THEN the heartbeat conversation is included
     expect(bgCount).toBe(1);
 
     // AND excluded from the foreground count
-    expect(countConversations("standard")).toBe(1);
+    expect(countConversations({ conversationType: "standard" })).toBe(1);
   });
 
   test("excludes standard conversations with group_id system:background from foreground count", () => {
@@ -432,7 +432,7 @@ describe("countConversations", () => {
 
     // WHEN counting foreground conversations
     // THEN the heartbeat is excluded
-    expect(countConversations("standard")).toBe(2);
+    expect(countConversations({ conversationType: "standard" })).toBe(2);
   });
 
   test('"scheduled" count returns only scheduled rows', () => {
@@ -443,7 +443,7 @@ describe("countConversations", () => {
 
     // WHEN counting scheduled conversations
     // THEN only the scheduled row is counted (background is excluded)
-    expect(countConversations("scheduled")).toBe(1);
+    expect(countConversations({ conversationType: "scheduled" })).toBe(1);
   });
 
   describe("archiveStatus", () => {
@@ -473,7 +473,12 @@ describe("countConversations", () => {
         a2.id,
       );
 
-      expect(countConversations("standard", "archived")).toBe(2);
+      expect(
+        countConversations({
+          conversationType: "standard",
+          archiveStatus: "archived",
+        }),
+      ).toBe(2);
     });
 
     test('archiveStatus "all" returns both', () => {
@@ -486,7 +491,12 @@ describe("countConversations", () => {
         archived.id,
       );
 
-      expect(countConversations("standard", "all")).toBe(2);
+      expect(
+        countConversations({
+          conversationType: "standard",
+          archiveStatus: "all",
+        }),
+      ).toBe(2);
     });
   });
 });
@@ -511,7 +521,10 @@ describe("listConversations", () => {
     createConversation("foreground-1");
 
     // WHEN listing background conversations
-    const bgList = listConversations(100, "background");
+    const bgList = listConversations({
+      limit: 100,
+      conversationType: "background",
+    });
 
     // THEN both background and heartbeat conversations are returned
     expect(bgList).toHaveLength(2);
@@ -532,7 +545,10 @@ describe("listConversations", () => {
     createConversation("foreground-1");
 
     // WHEN listing foreground conversations
-    const fgList = listConversations(100, "standard");
+    const fgList = listConversations({
+      limit: 100,
+      conversationType: "standard",
+    });
 
     // THEN only the foreground conversation is returned
     expect(fgList).toHaveLength(1);
@@ -549,14 +565,20 @@ describe("listConversations", () => {
     );
 
     // WHEN listing background conversations
-    const bgList = listConversations(100, "background");
+    const bgList = listConversations({
+      limit: 100,
+      conversationType: "background",
+    });
 
     // THEN it appears in the background list
     expect(bgList).toHaveLength(1);
     expect(bgList[0]!.title).toBe("schedule-routed");
 
     // AND not in the foreground list
-    const fgList = listConversations(100, "standard");
+    const fgList = listConversations({
+      limit: 100,
+      conversationType: "standard",
+    });
     expect(fgList).toHaveLength(0);
   });
 
@@ -567,7 +589,10 @@ describe("listConversations", () => {
     createConversation("foreground-1");
 
     // WHEN listing scheduled conversations
-    const scheduledList = listConversations(100, "scheduled");
+    const scheduledList = listConversations({
+      limit: 100,
+      conversationType: "scheduled",
+    });
 
     // THEN only the scheduled conversation is returned
     expect(scheduledList).toHaveLength(1);
@@ -592,7 +617,10 @@ describe("listConversations", () => {
     );
 
     // WHEN listing scheduled conversations
-    const scheduledList = listConversations(100, "scheduled");
+    const scheduledList = listConversations({
+      limit: 100,
+      conversationType: "scheduled",
+    });
 
     // THEN only the system:scheduled row appears
     expect(scheduledList).toHaveLength(1);
@@ -608,7 +636,10 @@ describe("listConversations", () => {
     });
 
     // WHEN listing scheduled conversations
-    const scheduledList = listConversations(100, "scheduled");
+    const scheduledList = listConversations({
+      limit: 100,
+      conversationType: "scheduled",
+    });
 
     // THEN the subagent run is excluded
     expect(scheduledList).toHaveLength(0);
@@ -627,7 +658,10 @@ describe("listConversations", () => {
       );
 
       // WHEN listing without an explicit archiveStatus
-      const rows = listConversations(100, "standard");
+      const rows = listConversations({
+        limit: 100,
+        conversationType: "standard",
+      });
 
       // THEN only the live conversation appears
       expect(rows).toHaveLength(1);
@@ -646,7 +680,11 @@ describe("listConversations", () => {
       );
 
       // WHEN listing with archiveStatus "archived"
-      const rows = listConversations(100, "standard", 0, "archived");
+      const rows = listConversations({
+        limit: 100,
+        conversationType: "standard",
+        archiveStatus: "archived",
+      });
 
       // THEN only the archived conversation appears
       expect(rows).toHaveLength(1);
@@ -665,7 +703,11 @@ describe("listConversations", () => {
       );
 
       // WHEN listing with archiveStatus "all"
-      const rows = listConversations(100, "standard", 0, "all");
+      const rows = listConversations({
+        limit: 100,
+        conversationType: "standard",
+        archiveStatus: "all",
+      });
 
       // THEN both conversations appear
       expect(rows).toHaveLength(2);
@@ -690,7 +732,11 @@ describe("listConversations", () => {
       );
 
       // WHEN listing archived background conversations
-      const rows = listConversations(100, "background", 0, "archived");
+      const rows = listConversations({
+        limit: 100,
+        conversationType: "background",
+        archiveStatus: "archived",
+      });
 
       // THEN only the archived background row appears
       expect(rows).toHaveLength(1);

package/src/runtime/routes/__tests__/conversation-list-routes.test.ts

@@ -246,6 +246,260 @@ describe("GET /v1/conversations — conversationType", () => {
   });
 });
 
+describe("GET /v1/conversations with groupId", () => {
+  function seedInGroup(title: string, groupId: string): string {
+    const conv = createConversation(title);
+    rawRun(
+      "test:fileIntoGroup",
+      "UPDATE conversations SET group_id = ? WHERE id = ?",
+      groupId,
+      conv.id,
+    );
+    return conv.id;
+  }
+
+  function seedPinned(title: string, displayOrder?: number): string {
+    const conv = createConversation(title);
+    rawRun(
+      "test:pinConversation",
+      "UPDATE conversations SET is_pinned = 1, group_id = 'system:pinned', display_order = ? WHERE id = ?",
+      displayOrder ?? null,
+      conv.id,
+    );
+    return conv.id;
+  }
+
+  beforeEach(() => {
+    clearConversations();
+  });
+
+  test("system:all returns only conversations in no group", async () => {
+    createConversation("ungrouped-1");
+    const group = createGroup("Car Chat");
+    seedInGroup("in-custom-group", group.id);
+    seedPinned("pinned-1");
+
+    const result = (await invoke({ groupId: "system:all" })) as ListResponse;
+
+    expect(result.conversations.map((c) => c.title)).toEqual(["ungrouped-1"]);
+  });
+
+  test("system:all matches rows whose group_id is NULL, not just the literal sentinel", async () => {
+    // `group_id` is only written when a conversation is filed somewhere, so
+    // almost every ungrouped row carries NULL. An equality-only predicate
+    // would return nothing at all here.
+    const conv = createConversation("never-filed");
+    rawRun(
+      "test:clearGroup",
+      "UPDATE conversations SET group_id = NULL WHERE id = ?",
+      conv.id,
+    );
+
+    const result = (await invoke({ groupId: "system:all" })) as ListResponse;
+
+    expect(result.conversations.map((c) => c.title)).toEqual(["never-filed"]);
+  });
+
+  test("system:pinned returns the Pinned section", async () => {
+    createConversation("ungrouped-1");
+    seedPinned("pinned-1");
+    seedPinned("pinned-2");
+
+    const result = (await invoke({ groupId: "system:pinned" })) as ListResponse;
+
+    expect(result.conversations.map((c) => c.title).sort()).toEqual([
+      "pinned-1",
+      "pinned-2",
+    ]);
+  });
+
+  test("a custom group id returns only that group's members", async () => {
+    const carChat = createGroup("Car Chat");
+    const recipes = createGroup("Recipes");
+    seedInGroup("car-1", carChat.id);
+    seedInGroup("car-2", carChat.id);
+    seedInGroup("recipe-1", recipes.id);
+    createConversation("ungrouped-1");
+
+    const result = (await invoke({ groupId: carChat.id })) as ListResponse;
+
+    expect(result.conversations.map((c) => c.title).sort()).toEqual([
+      "car-1",
+      "car-2",
+    ]);
+  });
+
+  test("a group-scoped page is ordered by the user's arrangement", async () => {
+    // Pinned and custom groups are drag-reorderable, so display order wins
+    // over recency inside a group.
+    seedPinned("third", 2);
+    seedPinned("first", 0);
+    seedPinned("second", 1);
+
+    const result = (await invoke({ groupId: "system:pinned" })) as ListResponse;
+
+    expect(result.conversations.map((c) => c.title)).toEqual([
+      "first",
+      "second",
+      "third",
+    ]);
+  });
+
+  test("a group-scoped page has no pinned rows appended to it", async () => {
+    // Injection exists so a client reading Pinned out of the unfiltered list
+    // still sees it. A caller that asked for one group gets that group.
+    const group = createGroup("Car Chat");
+    seedInGroup("car-1", group.id);
+    seedPinned("pinned-1");
+
+    const result = (await invoke({ groupId: group.id })) as ListResponse;
+
+    expect(result.conversations.map((c) => c.title)).toEqual(["car-1"]);
+  });
+
+  test("system:all keeps surfaced background and scheduled rows", async () => {
+    // Surfacing writes only `surfaced_at`, so a promoted row keeps its
+    // `system:background` / `system:scheduled` group id while the standard
+    // listing renders it in Recents. A group filter that matched NULL and
+    // "system:all" alone would drop it from the section that is supposed to
+    // show it.
+    const background = createConversation({
+      title: "surfaced-background",
+      conversationType: "background",
+    });
+    const scheduled = createConversation({
+      title: "surfaced-scheduled",
+      conversationType: "scheduled",
+    });
+    // The routed group id is the part that matters: heartbeat, reminders and
+    // schedule-job runs are filed into these system buckets, and surfacing
+    // does not clear that. A row left with a NULL group id would pass a
+    // NULL-only predicate and prove nothing.
+    rawRun(
+      "test:routeToSystemBucket",
+      "UPDATE conversations SET group_id = 'system:background', surfaced_at = ? WHERE id = ?",
+      Date.now(),
+      background.id,
+    );
+    rawRun(
+      "test:routeToSystemBucket",
+      "UPDATE conversations SET group_id = 'system:scheduled', surfaced_at = ? WHERE id = ?",
+      Date.now(),
+      scheduled.id,
+    );
+    createConversation("plain-ungrouped");
+
+    const result = (await invoke({ groupId: "system:all" })) as ListResponse;
+
+    expect(result.conversations.map((c) => c.title).sort()).toEqual([
+      "plain-ungrouped",
+      "surfaced-background",
+      "surfaced-scheduled",
+    ]);
+  });
+
+  test("system:all still excludes background rows that were never surfaced", async () => {
+    const quiet = createConversation({
+      title: "quiet-background",
+      conversationType: "background",
+    });
+    rawRun(
+      "test:routeToSystemBucket",
+      "UPDATE conversations SET group_id = 'system:background' WHERE id = ?",
+      quiet.id,
+    );
+    createConversation("plain-ungrouped");
+
+    const result = (await invoke({ groupId: "system:all" })) as ListResponse;
+
+    expect(result.conversations.map((c) => c.title)).toEqual([
+      "plain-ungrouped",
+    ]);
+  });
+
+  test("system:all and system:pinned partition the sections, never overlapping", async () => {
+    createConversation("ungrouped-1");
+    seedPinned("pinned-1");
+    const group = createGroup("Car Chat");
+    seedInGroup("car-1", group.id);
+
+    const ungrouped = (await invoke({ groupId: "system:all" })) as ListResponse;
+    const pinned = (await invoke({ groupId: "system:pinned" })) as ListResponse;
+    const custom = (await invoke({ groupId: group.id })) as ListResponse;
+
+    expect(ungrouped.conversations.map((c) => c.title)).toEqual([
+      "ungrouped-1",
+    ]);
+    expect(pinned.conversations.map((c) => c.title)).toEqual(["pinned-1"]);
+    expect(custom.conversations.map((c) => c.title)).toEqual(["car-1"]);
+  });
+
+  test("system buckets other than Pinned sort by recency, not stale display order", async () => {
+    // `display_order` persists through moves, so honouring it for
+    // system:background would order that section differently depending on
+    // whether it was fetched by conversationType or by groupId.
+    const older = createConversation({
+      title: "older",
+      conversationType: "background",
+    });
+    const newer = createConversation({
+      title: "newer",
+      conversationType: "background",
+    });
+    rawRun(
+      "test:staleOrder",
+      "UPDATE conversations SET surfaced_at = ?, display_order = 0, last_message_at = 1000 WHERE id = ?",
+      Date.now(),
+      older.id,
+    );
+    rawRun(
+      "test:staleOrder",
+      "UPDATE conversations SET surfaced_at = ?, display_order = 99, last_message_at = 2000 WHERE id = ?",
+      Date.now(),
+      newer.id,
+    );
+
+    const result = (await invoke({ groupId: "system:all" })) as ListResponse;
+
+    expect(result.conversations.map((c) => c.title)).toEqual([
+      "newer",
+      "older",
+    ]);
+  });
+
+  test("hasMore reflects the group's own total, not the whole table", async () => {
+    const group = createGroup("Car Chat");
+    seedInGroup("car-1", group.id);
+    seedInGroup("car-2", group.id);
+    for (let i = 0; i < 5; i++) {
+      createConversation(`ungrouped-${i}`);
+    }
+
+    const result = (await invoke({
+      groupId: group.id,
+      limit: "2",
+    })) as ListResponse;
+
+    expect(result.conversations).toHaveLength(2);
+    expect(result.hasMore).toBe(false);
+  });
+
+  test("omitting groupId is unchanged: every group is spanned and pinned still injects", async () => {
+    const group = createGroup("Car Chat");
+    seedInGroup("car-1", group.id);
+    createConversation("ungrouped-1");
+    seedPinned("pinned-1");
+
+    const result = (await invoke()) as ListResponse;
+
+    expect(result.conversations.map((c) => c.title).sort()).toEqual([
+      "car-1",
+      "pinned-1",
+      "ungrouped-1",
+    ]);
+  });
+});
+
 describe("GET /v1/conversations/unread-count", () => {
   const unreadCountHandler = findHandler(
     CONVERSATION_LIST_ROUTES,

package/src/runtime/routes/conversation-cli-routes.ts

@@ -44,12 +44,11 @@ function handleListCli({ body = {} }: RouteHandlerArgs) {
   // user sees archived rows alongside live ones in the picker.
   const includeArchived = (body.includeArchived as boolean) ?? false;
 
-  const rows = listConversations(
+  const rows = listConversations({
     limit,
-    "standard",
-    0,
-    includeArchived ? "all" : "active",
-  );
+    conversationType: "standard",
+    archiveStatus: includeArchived ? "all" : "active",
+  });
   return {
     conversations: rows.map((c) => ({
       id: c.id,
@@ -140,7 +139,7 @@ function handleExportCli({ body = {} }: RouteHandlerArgs) {
   let conversationId = body.conversationId as string | undefined;
 
   if (!conversationId) {
-    const all = listConversations(1);
+    const all = listConversations({ limit: 1 });
     if (all.length === 0) {
       throw new NotFoundError("No conversations found");
     }
@@ -151,12 +150,11 @@ function handleExportCli({ body = {} }: RouteHandlerArgs) {
   // behavior of letting `vellum export <prefix>` resolve an archived row.
   let conversation = getConversation(conversationId);
   if (!conversation) {
-    const all = listConversations(
-      Number.MAX_SAFE_INTEGER,
-      "standard",
-      0,
-      "all",
-    );
+    const all = listConversations({
+      limit: Number.MAX_SAFE_INTEGER,
+      conversationType: "standard",
+      archiveStatus: "all",
+    });
     const match = all.find((c) => c.id.startsWith(conversationId!));
     if (match) {
       conversation = match;

package/src/runtime/routes/conversation-list-routes.ts

@@ -27,6 +27,7 @@ import {
 } from "../../persistence/conversation-crud.js";
 import { resolveConversationId } from "../../persistence/conversation-key-store.js";
 import {
+  type ConversationListFilter,
   countConversations,
   countUnreadConversations,
   listConversations,
@@ -200,18 +201,19 @@ function handleListConversations({ queryParams = {} }: RouteHandlerArgs) {
       ? queryParams.originChannel
       : undefined;
 
-  let rows = listConversations(
-    limit,
-    conversationType,
-    offset,
-    archiveStatus,
-    originChannel,
-  );
-  const totalCount = countConversations(
+  const groupId =
+    queryParams.groupId !== undefined && queryParams.groupId !== ""
+      ? queryParams.groupId
+      : undefined;
+
+  const filter: ConversationListFilter = {
     conversationType,
     archiveStatus,
     originChannel,
-  );
+    groupId,
+  };
+  let rows = listConversations({ ...filter, limit, offset });
+  const totalCount = countConversations(filter);
 
   // On the first page, ensure all pinned conversations are included
   // even if they fall outside the paginated window. Pinned injection is
@@ -219,11 +221,19 @@ function handleListConversations({ queryParams = {} }: RouteHandlerArgs) {
   // rows in archive-time order, not pin order. Also skipped for
   // channel-scoped queries — those return only items matching the
   // requested origin channel; pinned items render in their own section.
+  //
+  // Skipped for group-scoped queries for the same reason: a caller asking
+  // for one group gets that group, and a client that fetches the Pinned
+  // section via `groupId=system:pinned` has no use for rows appended to
+  // some other group's page. This is the compatibility shim for clients
+  // that still read Pinned out of the unfiltered list; it goes away once
+  // every section fetches its own group.
   if (
     offset === 0 &&
     conversationType === "standard" &&
     archiveStatus === "active" &&
-    originChannel === undefined
+    originChannel === undefined &&
+    groupId === undefined
   ) {
     const pinned = listPinnedConversations(archiveStatus);
     const seen = new Set(rows.map((c) => c.id));
@@ -460,6 +470,13 @@ export const ROUTES: RouteDefinition[] = [
           enum: [...CHANNEL_IDS],
         },
       },
+      {
+        name: "groupId",
+        type: "string",
+        required: false,
+        description:
+          'Filter to a single group, so each sidebar section can load independently of the paginated list. Pass "system:all" for conversations in no group, "system:pinned" for the Pinned section, or a custom group id. A group-scoped request is ordered by the user\'s arrangement (display order, then recency) and never has pinned rows appended to it. Omit to span every group.',
+      },
     ],
     responseBody: listConversationsResponseSchema,
     handler: handleListConversations,

package/src/runtime/routes/debug-routes.ts

@@ -50,7 +50,10 @@ function getDebugInfo() {
   // Debug view counts every standard conversation, archived or not, so the
   // diagnostics report doesn't undercount after the route-level default
   // moved to "active".
-  const conversationCount = countConversations("standard", "all");
+  const conversationCount = countConversations({
+    conversationType: "standard",
+    archiveStatus: "all",
+  });
   const memoryItemCount = getMemoryItemCount();
   const dbSizeBytes = getDatabaseSizeBytes();
 

package/src/tools/conversation-groups/move_to_group.ts

@@ -93,9 +93,15 @@ export async function executeConversationMoveToGroup(
       `Moving into ${group.name} demotes it out of the Recents listing.`,
     );
   }
-  if (conversation.conversationType !== "standard") {
+  // Only Pinned and custom groups surface a hidden conversation. Recents is a
+  // removal target, and the Scheduled/Background groups are demotions, so
+  // claiming any of them made the conversation visible would misreport the
+  // outcome to the model and the user.
+  const surfacesConversation =
+    group.id === "system:pinned" || !group.id.startsWith("system:");
+  if (conversation.conversationType !== "standard" && surfacesConversation) {
     notes.push(
-      `Note: this is a ${conversation.conversationType} conversation, which stays hidden from the sidebar regardless of group.`,
+      `Note: this is a ${conversation.conversationType} conversation, so filing it here also surfaces it into the sidebar.`,
     );
   }