@vellumai/assistant 0.11.8-dev.202609030544.f41a019 → 0.11.8-dev.202609031226.a37d2ae

package/openapi.yaml

@@ -9978,7 +9978,11 @@ paths:
         unassigned conversations, Chats) with total and unread counts and no conversation rows. Lets a client know which
         sections exist, and what their badges say, without fetching any conversation list. Totals follow the standard
         listing visibility; unread applies the same rules as GET /v1/conversations/unread-count scoped to the section.
-        Chats is always present, even at zero: it is the leftover bucket and renders regardless."
+        Chats is always present, even at zero: it is the leftover bucket and renders regardless. Under the
+        `assistant-initiated-threads` flag an `assistant` section is also present at every count — the threads the
+        assistant started on its own, selectable as a list via `groupId=system:assistant` — and its rows are withheld
+        from Chats so the buckets stay disjoint. With the flag off no `assistant` row is emitted and those conversations
+        are counted in Chats as before."
       tags:
         - conversations
       responses:
@@ -10007,6 +10011,20 @@ paths:
                             - total
                             - unread
                           additionalProperties: false
+                        - type: object
+                          properties:
+                            kind:
+                              type: string
+                              const: assistant
+                            total:
+                              type: number
+                            unread:
+                              type: number
+                          required:
+                            - kind
+                            - total
+                            - unread
+                          additionalProperties: false
                         - type: object
                           properties:
                             kind:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.8-dev.202609030544.f41a019",
+  "version": "0.11.8-dev.202609031226.a37d2ae",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/conversation-pairing.test.ts

@@ -19,9 +19,17 @@ let addMessageShouldThrow = false;
 /** Simulated existing conversations for getConversation mock. */
 let mockExistingConversations: Record<
   string,
-  { id: string; source: string; title: string | null }
+  {
+    id: string;
+    source: string;
+    title: string | null;
+    conversationType?: string;
+  }
 > = {};
 
+/** Mutable arm for the assistant-initiated-threads gate mock. */
+let assistantInitiatedThreadsEnabled = false;
+
 const createConversationMock = mock((_opts?: unknown) => {
   if (createConversationShouldThrow) {
     throw new Error("DB write failed");
@@ -102,6 +110,12 @@ mock.module("../persistence/external-conversation-store.js", () => ({
   upsertOutboundBinding: upsertOutboundBindingMock,
 }));
 
+/* The registry resolves through workspace override files; a mutable arm keeps
+   these tests off the filesystem, mirroring the section-split suite. */
+mock.module("../config/assistant-initiated-threads-gate.js", () => ({
+  isAssistantInitiatedThreadsEnabled: () => assistantInitiatedThreadsEnabled,
+}));
+
 import { pairDeliveryWithConversation } from "../notifications/conversation-pairing.js";
 import type { NotificationSignal } from "../notifications/signal.js";
 import type {
@@ -162,6 +176,7 @@ describe("pairDeliveryWithConversation", () => {
     addMessageShouldThrow = false;
     mockExistingConversations = {};
     mockBindings = {};
+    assistantInitiatedThreadsEnabled = false;
   });
 
   // ── start_new_conversation (vellum) ─────────────────────────────────
@@ -1356,4 +1371,129 @@ describe("pairDeliveryWithConversation", () => {
     expect(result.conversationId).toBe("conv-001");
     expect(result.messageId).toBe("msg-001");
   });
+  // ── assistant.share → assistant-initiated thread (flag-gated) ────────
+
+  describe("assistant.share promotion under assistant-initiated-threads", () => {
+    const share = (overrides?: Partial<NotificationSignal>) =>
+      makeSignal({
+        requiresConversation: undefined,
+        sourceEventName: "assistant.share",
+        sourceContextId: "conv-heartbeat",
+        ...overrides,
+      });
+
+    test("flag on: a share from a background run materializes a section thread", async () => {
+      assistantInitiatedThreadsEnabled = true;
+      mockExistingConversations["conv-heartbeat"] = {
+        id: "conv-heartbeat",
+        source: "heartbeat",
+        title: null,
+        conversationType: "background",
+      };
+
+      const result = await pairDeliveryWithConversation(
+        share(),
+        "vellum" as NotificationChannel,
+        makeCopy({ conversationTitle: "Noticed something" }),
+      );
+
+      expect(result.createdNewConversation).toBe(true);
+      const callArgs = createConversationMock.mock.calls[0]![0] as Record<
+        string,
+        unknown
+      >;
+      expect(callArgs.source).toBe("assistant_initiated");
+      expect(callArgs.conversationType).toBe("standard");
+      expect(callArgs.title).toBe("Noticed something");
+    });
+
+    test("flag on: an unresolvable source context still materializes", async () => {
+      assistantInitiatedThreadsEnabled = true;
+
+      const result = await pairDeliveryWithConversation(
+        share({ sourceContextId: "cli-123" }),
+        "vellum" as NotificationChannel,
+        makeCopy(),
+      );
+
+      expect(result.createdNewConversation).toBe(true);
+      const callArgs = createConversationMock.mock.calls[0]![0] as Record<
+        string,
+        unknown
+      >;
+      expect(callArgs.source).toBe("assistant_initiated");
+    });
+
+    test("flag on: a share from a user-facing thread keeps the passive append", async () => {
+      assistantInitiatedThreadsEnabled = true;
+      mockExistingConversations["conv-user"] = {
+        id: "conv-user",
+        source: "user",
+        title: "Ongoing chat",
+        conversationType: "standard",
+      };
+
+      const result = await pairDeliveryWithConversation(
+        share({ sourceContextId: "conv-user" }),
+        "vellum" as NotificationChannel,
+        makeCopy(),
+      );
+
+      expect(result.createdNewConversation).toBe(false);
+      expect(result.conversationId).toBe("conv-user");
+      expect(createConversationMock).not.toHaveBeenCalled();
+    });
+
+    test("flag off: shares keep the passive append even from background runs", async () => {
+      mockExistingConversations["conv-heartbeat"] = {
+        id: "conv-heartbeat",
+        source: "heartbeat",
+        title: null,
+        conversationType: "background",
+      };
+
+      const result = await pairDeliveryWithConversation(
+        share(),
+        "vellum" as NotificationChannel,
+        makeCopy(),
+      );
+
+      expect(result.createdNewConversation).toBe(false);
+      expect(result.conversationId).toBe("conv-heartbeat");
+      expect(createConversationMock).not.toHaveBeenCalled();
+    });
+
+    test("flag on: an explicit conversationMetadata.source wins over promotion", async () => {
+      assistantInitiatedThreadsEnabled = true;
+
+      const result = await pairDeliveryWithConversation(
+        share({ conversationMetadata: { source: "schedule" } }),
+        "vellum" as NotificationChannel,
+        makeCopy(),
+      );
+
+      // The producer declared its own filing, so the passive rule holds.
+      expect(result.createdNewConversation).toBe(false);
+      expect(createConversationMock).not.toHaveBeenCalled();
+    });
+
+    test("flag on: non-share passive events keep the passive append", async () => {
+      assistantInitiatedThreadsEnabled = true;
+      mockExistingConversations["conv-heartbeat"] = {
+        id: "conv-heartbeat",
+        source: "heartbeat",
+        title: null,
+        conversationType: "background",
+      };
+
+      const result = await pairDeliveryWithConversation(
+        share({ sourceEventName: "scheduler.reminder_fired" }),
+        "vellum" as NotificationChannel,
+        makeCopy(),
+      );
+
+      expect(result.createdNewConversation).toBe(false);
+      expect(createConversationMock).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/config/__tests__/assistant-initiated-threads-gate.test.ts

@@ -0,0 +1,61 @@
+/**
+ * The gate reads a string-valued flag that does not always arrive as a
+ * string.
+ *
+ * The registry and the gateway's persisted store carry the declared `"on"` /
+ * `"off"` strings. The gateway's env-override path does not: its parser
+ * (`feature-flag-env-overrides.ts`) treats `on` as a truthy *word* and
+ * coerces it to boolean `true`, then applies env overrides last — so
+ * `VELLUM_FLAG_ASSISTANT_INITIATED_THREADS=on` reaches the daemon as `true`.
+ *
+ * A strict `=== "on"` therefore read the documented env kill-switch as OFF,
+ * and did it silently: the section just never rendered. That shipped in the
+ * first cut of this gate and cost an afternoon of QA, which is why both
+ * shapes are pinned here rather than only the one the registry emits.
+ */
+
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+let flagValue: boolean | string = "off";
+
+mock.module("../assistant-feature-flags.js", () => ({
+  getAssistantFeatureFlagValue: () => flagValue,
+}));
+
+const { isAssistantInitiatedThreadsEnabled } = await import(
+  "../assistant-initiated-threads-gate.js"
+);
+
+afterEach(() => {
+  flagValue = "off";
+});
+
+describe("isAssistantInitiatedThreadsEnabled", () => {
+  test('enabled by the declared string "on" (registry / persisted store)', () => {
+    flagValue = "on";
+    expect(isAssistantInitiatedThreadsEnabled()).toBe(true);
+  });
+
+  test("enabled by boolean true (the gateway's env-override coercion)", () => {
+    // The regression. `VELLUM_FLAG_ASSISTANT_INITIATED_THREADS=on` arrives
+    // here as `true`, never as "on".
+    flagValue = true;
+    expect(isAssistantInitiatedThreadsEnabled()).toBe(true);
+  });
+
+  test('disabled by the declared string "off"', () => {
+    flagValue = "off";
+    expect(isAssistantInitiatedThreadsEnabled()).toBe(false);
+  });
+
+  test("disabled by boolean false (env `=off` coercion)", () => {
+    flagValue = false;
+    expect(isAssistantInitiatedThreadsEnabled()).toBe(false);
+  });
+
+  test("fails closed on an unrecognized arm", () => {
+    // A future A/B value this gate has no opinion about must not read as on.
+    flagValue = "variant-b";
+    expect(isAssistantInitiatedThreadsEnabled()).toBe(false);
+  });
+});

package/src/config/assistant-initiated-threads-gate.ts

@@ -0,0 +1,50 @@
+import { getAssistantFeatureFlagValue } from "./assistant-feature-flags.js";
+import type { AssistantConfig } from "./schema.js";
+
+const ASSISTANT_INITIATED_THREADS_FLAG_KEY =
+  "assistant-initiated-threads" as const;
+
+/**
+ * Whether the conversations the assistant started on its own are split into
+ * their own sidebar section instead of sitting in Chats.
+ *
+ * Read through {@link getAssistantFeatureFlagValue} rather than
+ * `isAssistantFeatureFlagEnabled`, because the flag is string-valued: that
+ * helper coerces with `!!`, and `!!"off"` is `true`, so the boolean form would
+ * report the off arm as on.
+ *
+ * A read-side gate only. The rows exist either way — every notification
+ * delivery has always materialized one (`notifications/conversation-pairing.ts`)
+ * — so turning the flag off puts them back in Chats and takes the `assistant`
+ * row out of the section index, with nothing to migrate in either direction.
+ *
+ * This is the *only* gate on the feature, which is why the flag is
+ * assistant-scope rather than `both`. Clients render the section on the
+ * presence of the index row, because that row is what says the daemon has
+ * withheld those conversations from Chats. A second, client-side gate could
+ * only ever hide a section whose rows have already been withheld — losing
+ * those threads rather than reverting the feature — so there deliberately
+ * isn't one.
+ */
+export function isAssistantInitiatedThreadsEnabled(
+  config?: AssistantConfig,
+): boolean {
+  const value = getAssistantFeatureFlagValue(
+    ASSISTANT_INITIATED_THREADS_FLAG_KEY,
+    config,
+  );
+  /* Both shapes are the same answer, and the on arm arrives as either one
+     depending on which layer resolved it.
+
+     The registry and the gateway's persisted store carry the declared string
+     (`"on"`). The gateway's env-override path does not: its parser treats
+     `on` as a truthy word (`TRUTHY = {"true","1","yes","on"}` in
+     `feature-flag-env-overrides.ts`) and coerces it to boolean `true`, then
+     applies env last — so `VELLUM_FLAG_ASSISTANT_INITIATED_THREADS=on`
+     reaches the daemon as `true`, not `"on"`.
+
+     A strict `=== "on"` therefore reads the env kill-switch as OFF, which is
+     the exact opposite of what an operator setting it intends, and it fails
+     silently: the section simply does not render. Accept both. */
+  return value === true || value === "on";
+}

package/src/config/feature-flag-registry.json

@@ -36,6 +36,15 @@
       "defaultEnabled": "off",
       "values": ["off", "on"]
     },
+    {
+      "id": "assistant-initiated-threads",
+      "scope": "assistant",
+      "key": "assistant-initiated-threads",
+      "label": "Assistant-Initiated Threads",
+      "description": "Gates the sidebar section collecting the conversations the assistant started on its own: rows stamped `source='assistant_initiated'` at creation by producers that opt a thread in (heartbeat realizations worth the user's time; nothing stamps it yet, so the section starts empty and holds only new threads by construction). Transactional notification trails keep `source='notification'` and stay in Chats and the bell. When on, the daemon emits an `assistant` row from the section index and withholds member conversations from the Chats bucket; when off, they stay in Chats and no `assistant` row is emitted, which is the shipped behavior. Deliberately daemon-scope only: the index row is self-describing, so clients render the section on its presence rather than on a flag of their own. A second client-side gate could only hide a section whose rows the daemon has already withheld from Chats, which would lose those threads instead of reverting the feature. String-valued so future A/B arms can be added as new values.",
+      "defaultEnabled": "off",
+      "values": ["off", "on"]
+    },
     {
       "id": "experiment-activation-flow-2026-06-03",
       "scope": "both",

package/src/notifications/conversation-pairing.ts

@@ -23,11 +23,13 @@
 import type { ConversationStrategy } from "../channels/config.js";
 import { getConversationStrategy } from "../channels/config.js";
 import type { ChannelId } from "../channels/types.js";
+import { isAssistantInitiatedThreadsEnabled } from "../config/assistant-initiated-threads-gate.js";
 import {
   addMessage,
   createConversation,
   getConversation,
 } from "../persistence/conversation-crud.js";
+import { ASSISTANT_INITIATED_SOURCE } from "../persistence/conversation-types.js";
 import {
   getBindingByChannelChat,
   upsertOutboundBinding,
@@ -106,13 +108,77 @@ export interface PairingOptions {
  * Errors are caught and logged — this function never throws so the
  * notification pipeline is not disrupted by pairing failures.
  */
-export async function pairDeliveryWithConversation(
+/**
+ * The event the assistant emits when it has a thought worth the user's time
+ * ("assistant.share" - the notifications skill's default), as opposed to a
+ * transactional request or a system alert.
+ */
+const ASSISTANT_SHARE_EVENT = "assistant.share";
+
+/**
+ * Promote a background share into an assistant-initiated thread, under the
+ * `assistant-initiated-threads` flag.
+ *
+ * The heartbeat's "have a thought, share it" path emits an assistant.share
+ * signal from its own background conversation, and the passive-vellum rule
+ * below would append the body there - a row the sidebar never shows. When the
+ * section exists, that share is exactly what it is for, so the signal is
+ * rewritten to materialize a fresh standard conversation stamped
+ * {@link ASSISTANT_INITIATED_SOURCE}, which is the section's membership mark.
+ *
+ * Deliberately narrow, in every direction it can be:
+ * - vellum channel only: other channels deliver the share as a native
+ *   message and need no in-app thread;
+ * - assistant.share only: transactional events keep their own pairing
+ *   rules, and their threads stay out of the section by source;
+ * - only when the producing conversation is a background/scheduled run (or
+ *   nothing resolvable): a share emitted from inside a user-facing thread
+ *   keeps the append, since the user is already looking at that thread;
+ * - never over an explicit `conversationMetadata.source` or an existing
+ *   `requiresConversation`: a producer that declared its own filing wins.
+ *
+ * Flag off, the signal passes through untouched and shares keep the passive
+ * append: nothing changes for anyone outside the rollout.
+ */
+function withAssistantInitiatedThread(
   signal: NotificationSignal,
   channel: NotificationChannel,
+): NotificationSignal {
+  if (
+    channel !== "vellum" ||
+    signal.sourceEventName !== ASSISTANT_SHARE_EVENT ||
+    signal.requiresConversation === true ||
+    signal.conversationMetadata?.source !== undefined ||
+    !isAssistantInitiatedThreadsEnabled()
+  ) {
+    return signal;
+  }
+  const producing = getConversation(signal.sourceContextId);
+  if (
+    producing &&
+    producing.conversationType !== "background" &&
+    producing.conversationType !== "scheduled"
+  ) {
+    return signal;
+  }
+  return {
+    ...signal,
+    requiresConversation: true,
+    conversationMetadata: {
+      ...signal.conversationMetadata,
+      source: ASSISTANT_INITIATED_SOURCE,
+    },
+  };
+}
+
+export async function pairDeliveryWithConversation(
+  rawSignal: NotificationSignal,
+  channel: NotificationChannel,
   copy: RenderedChannelCopy,
   options?: PairingOptions,
 ): Promise<PairingResult> {
   try {
+    const signal = withAssistantInitiatedThread(rawSignal, channel);
     const strategy = getConversationStrategy(channel as ChannelId);
 
     if (strategy === "not_deliverable" || strategy === "push_only") {
@@ -490,7 +556,7 @@ export async function pairDeliveryWithConversation(
     };
   } catch (err) {
     log.error(
-      { err, signalId: signal.signalId, channel },
+      { err, signalId: rawSignal.signalId, channel },
       "Failed to pair notification delivery with conversation — continuing without pairing",
     );
     const fallbackStrategy = (() => {

package/src/persistence/conversation-queries.ts

@@ -25,6 +25,8 @@ import { ensureDisplayOrderMigration } from "./conversation-display-order-migrat
 import { ensureGroupMigration } from "./conversation-group-migration.js";
 import { searchMessageIdsLexical } from "./conversation-search-lexical.js";
 import {
+  ASSISTANT_INITIATED_GROUP_ID,
+  ASSISTANT_INITIATED_SOURCE,
   type ConversationType,
   NATIVE_ORIGIN_CHANNEL,
   PINNED_GROUP_ID,
@@ -213,6 +215,58 @@ function notBackgroundVisibilitySql(alias = "conversations"): string {
   );
 }
 
+/**
+ * Raw SQL predicate for "a thread the assistant started on its own": the rows
+ * stamped {@link ASSISTANT_INITIATED_SOURCE} at creation by a producer that
+ * opted the thread into the section.
+ *
+ * Membership rides `source` rather than `group_id` because those rows are
+ * filed nowhere — see {@link ASSISTANT_INITIATED_GROUP_ID} for why the section
+ * is still named as a group id. It is a dedicated source rather than the
+ * notification pipeline's `'notification'`, whose rows are the transactional
+ * request trails (guardian approvals, confirmation / access / question /
+ * tool-grant requests, channel deliveries) that belong to the bell and to
+ * Chats - see {@link ASSISTANT_INITIATED_SOURCE} for the full rationale.
+ */
+function assistantInitiatedSql(alias = "conversations"): string {
+  return `(${alias}.source = '${ASSISTANT_INITIATED_SOURCE}' AND ${ungroupedSql(alias)})`;
+}
+
+/**
+ * The complement of {@link assistantInitiatedSql}, spelled out rather than
+ * wrapped in `NOT`.
+ *
+ * `source` is nullable and the overwhelming majority of rows carry NULL, so
+ * `NOT (source = '...')` evaluates to NULL for them under SQL's three-valued
+ * logic and the WHERE clause drops them. Negating the column naively would
+ * therefore not withhold one section from Chats - it would empty Chats.
+ */
+function notAssistantInitiatedSql(alias = "conversations"): string {
+  return `(${alias}.source IS NULL OR ${alias}.source != '${ASSISTANT_INITIATED_SOURCE}' OR NOT ${ungroupedSql(alias)})`;
+}
+
+/**
+ * Raw SQL predicate for {@link UNGROUPED_GROUP_ID}: 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
+ * {@link conversationTypeClause}, which admits the surfaced ones and excludes
+ * the rest; matching on group id alone here would drop them.
+ *
+ * Named because two sections are carved out of this same set — Chats and the
+ * assistant-initiated threads — and they have to agree on what it contains or
+ * a row lands in both or neither.
+ */
+function ungroupedSql(alias = "conversations"): string {
+  return (
+    `(${alias}.group_id IS NULL` +
+    ` OR (${alias}.group_id LIKE 'system:%' AND ${alias}.group_id != '${PINNED_GROUP_ID}'))`
+  );
+}
+
 /**
  * SQL predicate selecting which bucket {@link listConversations} and
  * {@link countConversations} return, keyed by the canonical
@@ -293,6 +347,21 @@ export interface ConversationListFilter {
    * row instead of paging past runs it would skip.
    */
   foregroundOnly?: true;
+  /**
+   * Withhold the threads the assistant started on its own
+   * ({@link assistantInitiatedSql}) from the result.
+   *
+   * The exact complement of `groupId: ASSISTANT_INITIATED_GROUP_ID`, and the
+   * other half of splitting that section out of Chats: without it those rows
+   * would be counted and listed twice, once in their own section and once in
+   * the leftover bucket that never excluded them. Being the exact complement
+   * matters as much as the exclusion — a thread the user pinned or filed into
+   * a custom group is not in the assistant section, so this must not withhold
+   * it from the section that does hold it. Only `true` narrows; omit to keep
+   * every row, which is what every caller does while the
+   * `assistant-initiated-threads` flag is off.
+   */
+  excludeAssistantInitiated?: true;
 }
 
 export interface ConversationListQuery extends ConversationListFilter {
@@ -313,16 +382,15 @@ export interface ConversationListQuery extends ConversationListFilter {
  * declared in `schema/conversations.ts`.
  */
 function groupIdClause(groupId: string) {
+  if (groupId === ASSISTANT_INITIATED_GROUP_ID) {
+    // Not a `group_id` match: `source` decides membership. See
+    // ASSISTANT_INITIATED_GROUP_ID. Still narrowed to the ungrouped set,
+    // because filing one of these threads into a custom group — or pinning it
+    // — must move it there rather than leave it in two sections at once.
+    return sql.raw(assistantInitiatedSql());
+  }
   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}))`;
+    return sql.raw(ungroupedSql());
   }
   // `group_id` is single-valued and authoritative, so a row belongs to
   // exactly one section by construction. `is_pinned` is a derived duplicate
@@ -376,6 +444,7 @@ function conversationListWhere(filter: ConversationListFilter) {
     groupId,
     needsAttention,
     foregroundOnly,
+    excludeAssistantInitiated,
   } = filter;
   return and(
     conversationTypeClause(conversationType),
@@ -384,6 +453,7 @@ function conversationListWhere(filter: ConversationListFilter) {
     groupId ? groupIdClause(groupId) : undefined,
     ...(needsAttention ? unseenAttentionStateConditions() : []),
     foregroundOnly ? sql.raw(notBackgroundVisibilitySql()) : undefined,
+    excludeAssistantInitiated ? sql.raw(notAssistantInitiatedSql()) : undefined,
   );
 }
 
@@ -699,11 +769,34 @@ export interface ConversationSectionCount {
 export interface ConversationSectionCounts {
   groups: Array<{ groupId: string } & ConversationSectionCount>;
   channels: Array<{ channel: string } & ConversationSectionCount>;
+  /**
+   * The assistant-initiated section, present only when the caller asked for
+   * the split ({@link CountConversationSectionsOptions.splitAssistantInitiated}).
+   * Absent — not zero — when it did not, so a caller that never asked cannot
+   * mistake "not split out" for "split out and empty".
+   *
+   * When present, these rows are withheld from `channels`, keeping the two
+   * axes disjoint the way `groups` and `channels` already are.
+   */
+  assistantInitiated?: ConversationSectionCount;
+}
+
+export interface CountConversationSectionsOptions {
+  /**
+   * Count the threads the assistant started on its own as their own section
+   * and withhold them from the channel buckets. Off by default: the caller
+   * that knows about the `assistant-initiated-threads` flag turns it on, and
+   * every other caller keeps today's shape.
+   */
+  splitAssistantInitiated?: boolean;
 }
 
-export function countConversationSections(): ConversationSectionCounts {
+export function countConversationSections(
+  options: CountConversationSectionsOptions = {},
+): ConversationSectionCounts {
   ensureGroupMigration();
   const db = getDb();
+  const { splitAssistantInitiated = false } = options;
 
   /* `countUnreadConversations` gets the same effect with an INNER JOIN and
      the unseen conditions in its WHERE; here every row must be counted and
@@ -747,12 +840,48 @@ export function countConversationSections(): ConversationSectionCounts {
         conversationTypeClause("standard"),
         isNull(conversations.archivedAt),
         groupIdClause(UNGROUPED_GROUP_ID),
+        /* The split's other half. These rows are ungrouped and natively
+           attributed, so without this they stay in the Chats bucket and get
+           counted in both sections at once. */
+        splitAssistantInitiated
+          ? sql.raw(notAssistantInitiatedSql())
+          : undefined,
       ),
     )
     .groupBy(effectiveChannel)
     .all();
 
-  return { groups, channels };
+  if (!splitAssistantInitiated) {
+    return { groups, channels };
+  }
+
+  /* Composed from the same predicates as the buckets above rather than
+     restated, so this section's badge cannot drift from theirs: same standard
+     listing visibility, same active-rows-only rule, same unread CASE. */
+  const [assistantInitiated] = db
+    .select({ total: count(), unread })
+    .from(conversations)
+    .leftJoin(conversationAssistantAttentionState, attentionJoin)
+    .where(
+      and(
+        conversationTypeClause("standard"),
+        isNull(conversations.archivedAt),
+        groupIdClause(ASSISTANT_INITIATED_GROUP_ID),
+      ),
+    )
+    .all();
+
+  return {
+    groups,
+    channels,
+    /* The aggregate is over no GROUP BY, so it always yields one row — but it
+       yields `unread: null` rather than 0 when no row matched, because SUM
+       over an empty set is NULL. */
+    assistantInitiated: {
+      total: assistantInitiated?.total ?? 0,
+      unread: assistantInitiated?.unread ?? 0,
+    },
+  };
 }
 
 /**

package/src/persistence/conversation-types.ts

@@ -82,10 +82,7 @@ export function isBackgroundConversationType(
  * columns into one label.
  */
 export type ConversationKind =
-  | "user"
-  | "background"
-  | "background_memory_consolidation"
-  | "scheduled";
+  "user" | "background" | "background_memory_consolidation" | "scheduled";
 
 /**
  * Single classifier shared by the LLM-context routes and the notification
@@ -451,6 +448,41 @@ export function isReplyPushIneligibleUserMessage(
 export const UNGROUPED_GROUP_ID = "system:all";
 export const PINNED_GROUP_ID = "system:pinned";
 
+/**
+ * The `conversations.source` that makes a thread a member of the
+ * assistant-initiated section ({@link ASSISTANT_INITIATED_GROUP_ID}).
+ *
+ * Opt-in and stamped at creation, by a producer declaring "this is a thread
+ * I started because it is worth the user's time" - a heartbeat realization,
+ * an observation the user did not ask for. Deliberately NOT the notification
+ * pipeline's `'notification'`: the conversations that stamp carries are the
+ * transactional flows (guardian call approvals, confirmation / access /
+ * question / tool-grant requests, channel delivery trails - the
+ * `requiresConversation` producers), which belong to the bell and to Chats,
+ * and matching on it would also sweep every historical row into the section
+ * the day the flag turns on. A dedicated source makes membership all-new by
+ * construction: nothing stamps it until a producer passes it through
+ * `conversationMetadata.source` on its notification signal (see
+ * `notifications/conversation-pairing.ts`), so the section holds exactly the
+ * threads written for it and nothing retroactively.
+ */
+// FROZEN: persisted `conversations.source` value. Never rename it.
+export const ASSISTANT_INITIATED_SOURCE = "assistant_initiated";
+
+/**
+ * The section holding the conversations the assistant started on its own:
+ * the threads stamped {@link ASSISTANT_INITIATED_SOURCE} at creation.
+ *
+ * A pseudo-group in the same sense as {@link UNGROUPED_GROUP_ID}: no row
+ * carries it in `group_id`. Those conversations are filed nowhere (NULL
+ * `group_id`), so without the split they land in Chats; membership is
+ * decided by `source`, not by the column this id names. It is spelled as a
+ * group id anyway so a client selects the section through the `groupId`
+ * parameter every other section already uses, rather than through a filter
+ * only this one section knows about.
+ */
+export const ASSISTANT_INITIATED_GROUP_ID = "system:assistant";
+
 /**
  * The `origin_channel` value for a conversation started in Vellum itself
  * rather than arriving from an external channel.

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

@@ -0,0 +1,359 @@
+/**
+ * The `assistant-initiated-threads` split: the threads the assistant started
+ * on its own (`source = 'assistant_initiated'`, opt-in at creation) become
+ * their own sidebar section instead of sitting in Chats.
+ *
+ * The flag is the whole point of these tests. It is a read-side gate over rows
+ * that exist either way, so the off arm must be byte-identical to the behavior
+ * that shipped before the section existed — that is what makes the feature
+ * reversible without a migration. Both arms are asserted for every claim.
+ *
+ * The gate module is mocked rather than the flag registry: the registry
+ * resolves through workspace override files, and a test that wrote those would
+ * be asserting the resolver's behavior rather than this route's.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Avoid spinning up the real event hub for the pinned/groups branches.
+mock.module("../../assistant-event-hub.js", () => ({
+  assistantEventHub: {
+    publish: async () => {},
+    subscribe: () => () => {},
+  },
+  broadcastMessage: () => {},
+}));
+
+let flagEnabled = false;
+mock.module("../../../config/assistant-initiated-threads-gate.js", () => ({
+  isAssistantInitiatedThreadsEnabled: () => flagEnabled,
+}));
+
+import { projectAssistantMessage } from "../../../persistence/conversation-attention-store.js";
+import { createConversation } from "../../../persistence/conversation-crud.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";
+import { ROUTES as CONVERSATION_LIST_ROUTES } from "../conversation-list-routes.js";
+import type { RouteDefinition } from "../types.js";
+
+await initializeDb();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function findHandler(routes: RouteDefinition[], operationId: string) {
+  const route = routes.find((r) => r.operationId === operationId);
+  if (!route) {
+    throw new Error(`Route ${operationId} not found`);
+  }
+  return route.handler;
+}
+
+const sectionsHandler = findHandler(
+  CONVERSATION_LIST_ROUTES,
+  "getConversationSections",
+);
+const listHandler = findHandler(CONVERSATION_LIST_ROUTES, "listConversations");
+
+interface SectionRow {
+  kind: "pinned" | "group" | "channel" | "chats" | "assistant";
+  channelId?: string;
+  groupId?: string;
+  total: number;
+  unread: number;
+}
+
+function invokeSections(): SectionRow[] {
+  return (sectionsHandler({}) as { sections: SectionRow[] }).sections;
+}
+
+interface ListResponse {
+  conversations: Array<{ id: string; title: string }>;
+}
+
+function invokeList(queryParams: Record<string, string> = {}): ListResponse {
+  return listHandler({ queryParams }) as ListResponse;
+}
+
+function titlesFrom(response: ListResponse): string[] {
+  return response.conversations.map((c) => c.title).sort();
+}
+
+/**
+ * A thread a producer opted into the assistant-initiated section: a
+ * standard-type conversation, filed nowhere, stamped
+ * `source: 'assistant_initiated'` at creation (ASSISTANT_INITIATED_SOURCE).
+ */
+function seedAssistantInitiated(title: string): string {
+  return createConversation({ title, source: "assistant_initiated" }).id;
+}
+
+/**
+ * A transactional notification trail - what the guardian request flows and
+ * channel deliveries materialize (`source: 'notification'`, see
+ * `notifications/conversation-pairing.ts`). Never a member of the section:
+ * these belong to the bell and to Chats.
+ */
+function seedNotificationTrail(title: string): string {
+  return createConversation({ title, source: "notification" }).id;
+}
+
+function seedUnseen(conversationId: string): void {
+  projectAssistantMessage({
+    conversationId,
+    messageId: `msg-${conversationId}`,
+    messageAt: Date.now(),
+  });
+}
+
+function stampChannel(conversationId: string, channel: string): void {
+  rawRun(
+    "test:stampChannel",
+    "UPDATE conversations SET origin_channel = ? WHERE id = ?",
+    channel,
+    conversationId,
+  );
+}
+
+function pin(conversationId: string): void {
+  rawRun(
+    "test:pinConversation",
+    "UPDATE conversations SET is_pinned = 1, group_id = 'system:pinned' WHERE id = ?",
+    conversationId,
+  );
+}
+
+function fileIntoGroup(conversationId: string, groupId: string): void {
+  rawRun(
+    "test:fileIntoGroup",
+    "UPDATE conversations SET group_id = ? WHERE id = ?",
+    groupId,
+    conversationId,
+  );
+}
+
+beforeEach(() => {
+  flagEnabled = false;
+  getDb().delete(conversations).run();
+});
+
+// ---------------------------------------------------------------------------
+// Flag off — the shipped behavior, unchanged
+// ---------------------------------------------------------------------------
+
+describe("assistant-initiated threads — flag off", () => {
+  test("emits no assistant section, and the threads stay counted in Chats", () => {
+    seedAssistantInitiated("overnight-realization");
+    createConversation({ title: "user-thread" });
+
+    const sections = invokeSections();
+
+    expect(sections.some((s) => s.kind === "assistant")).toBe(false);
+    expect(sections).toContainEqual({ kind: "chats", total: 2, unread: 0 });
+  });
+
+  test("the threads stay listed in the standard list", () => {
+    seedAssistantInitiated("overnight-realization");
+    createConversation({ title: "user-thread" });
+
+    expect(titlesFrom(invokeList())).toEqual([
+      "overnight-realization",
+      "user-thread",
+    ]);
+  });
+
+  test("their unread still counts toward Chats", () => {
+    seedUnseen(seedAssistantInitiated("noticed-something"));
+    createConversation({ title: "user-thread" });
+
+    expect(invokeSections()).toContainEqual({
+      kind: "chats",
+      total: 2,
+      unread: 1,
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Flag on — the split
+// ---------------------------------------------------------------------------
+
+describe("assistant-initiated threads — flag on", () => {
+  beforeEach(() => {
+    flagEnabled = true;
+  });
+
+  test("the threads move out of Chats into their own section", () => {
+    seedAssistantInitiated("overnight-realization");
+    seedAssistantInitiated("noticed-something");
+    createConversation({ title: "user-thread" });
+
+    const sections = invokeSections();
+
+    expect(sections).toContainEqual({ kind: "assistant", total: 2, unread: 0 });
+    expect(sections).toContainEqual({ kind: "chats", total: 1, unread: 0 });
+  });
+
+  test("the section renders at zero, the way Chats does", () => {
+    createConversation({ title: "user-thread" });
+
+    expect(invokeSections()).toContainEqual({
+      kind: "assistant",
+      total: 0,
+      unread: 0,
+    });
+  });
+
+  test("unread follows the section, and is not double-counted in Chats", () => {
+    seedUnseen(seedAssistantInitiated("noticed-something"));
+    seedAssistantInitiated("read-already");
+    seedUnseen(createConversation({ title: "user-thread" }).id);
+
+    const sections = invokeSections();
+
+    expect(sections).toContainEqual({ kind: "assistant", total: 2, unread: 1 });
+    expect(sections).toContainEqual({ kind: "chats", total: 1, unread: 1 });
+  });
+
+  test("the split leaves channel sections alone", () => {
+    seedAssistantInitiated("overnight-realization");
+    stampChannel(createConversation({ title: "slack-thread" }).id, "slack");
+
+    const sections = invokeSections();
+
+    expect(sections).toContainEqual({ kind: "assistant", total: 1, unread: 0 });
+    expect(sections).toContainEqual({
+      kind: "channel",
+      channelId: "slack",
+      total: 1,
+      unread: 0,
+    });
+  });
+
+  test("groupId=system:assistant lists exactly those threads", () => {
+    seedAssistantInitiated("overnight-realization");
+    seedAssistantInitiated("noticed-something");
+    createConversation({ title: "user-thread" });
+
+    expect(titlesFrom(invokeList({ groupId: "system:assistant" }))).toEqual([
+      "noticed-something",
+      "overnight-realization",
+    ]);
+  });
+
+  test("the standard list withholds them, and keeps every NULL-source row", () => {
+    // The regression this guards: `NOT (source = '...')` is NULL for the
+    // NULL-source rows that make up most of the list, so a naive negation
+    // would return an empty list rather than one section fewer.
+    seedAssistantInitiated("overnight-realization");
+    createConversation({ title: "user-thread" });
+    createConversation({ title: "another-user-thread" });
+
+    expect(titlesFrom(invokeList())).toEqual([
+      "another-user-thread",
+      "user-thread",
+    ]);
+  });
+
+  test("a list already scoped to the section is not narrowed to nothing", () => {
+    // `groupId=system:assistant` selects on the same column the exclusion
+    // negates, so applying both would return an empty page for the one caller
+    // that actually wants these rows.
+    seedAssistantInitiated("overnight-realization");
+
+    expect(titlesFrom(invokeList({ groupId: "system:assistant" }))).toEqual([
+      "overnight-realization",
+    ]);
+  });
+
+  test("a pinned thread belongs to Pinned, not to both", () => {
+    // Section membership is single-valued everywhere else in the sidebar, and
+    // this section is carved out of the same ungrouped set Chats is, so
+    // pinning has to move a thread rather than duplicate it.
+    pin(seedAssistantInitiated("pinned-realization"));
+    seedAssistantInitiated("ordinary-realization");
+
+    const sections = invokeSections();
+
+    expect(sections).toContainEqual({ kind: "assistant", total: 1, unread: 0 });
+    expect(sections).toContainEqual({ kind: "pinned", total: 1, unread: 0 });
+    expect(titlesFrom(invokeList({ groupId: "system:assistant" }))).toEqual([
+      "ordinary-realization",
+    ]);
+  });
+
+  test("transactional notification trails are not members, and stay in Chats", () => {
+    // The membership source is opt-in precisely so the flag turning on cannot
+    // sweep the historical guardian-request and channel-delivery trails
+    // (`source = 'notification'`) into the section: only threads written for
+    // the section, from the moment producers start stamping its source, are
+    // members.
+    seedNotificationTrail("approve-this-call");
+    seedAssistantInitiated("overnight-realization");
+
+    const sections = invokeSections();
+
+    expect(sections).toContainEqual({ kind: "assistant", total: 1, unread: 0 });
+    expect(sections).toContainEqual({ kind: "chats", total: 1, unread: 0 });
+    expect(titlesFrom(invokeList())).toEqual(["approve-this-call"]);
+    expect(titlesFrom(invokeList({ groupId: "system:assistant" }))).toEqual([
+      "overnight-realization",
+    ]);
+  });
+
+  test("a thread filed into a custom group leaves the section and stays listable", () => {
+    // The exclusion is the complement of the section, so a thread that moved
+    // out of the section must not stay excluded from the list of the group it
+    // moved into — otherwise filing one makes it unreachable.
+    const group = createGroup("Reading List");
+    const filed = seedAssistantInitiated("filed-realization");
+    fileIntoGroup(filed, group.id);
+
+    expect(invokeSections()).toContainEqual({
+      kind: "assistant",
+      total: 0,
+      unread: 0,
+    });
+    expect(titlesFrom(invokeList({ groupId: group.id }))).toEqual([
+      "filed-realization",
+    ]);
+  });
+
+  test("the Archive view keeps archived section threads", () => {
+    // Archive asks archiveStatus=archived with no groupId, and the section
+    // only ever lists active rows, so the split's exclusion must not reach
+    // archived reads or an archived section thread is visible nowhere.
+    const archived = seedAssistantInitiated("archived-realization");
+    rawRun(
+      "test:archive",
+      "UPDATE conversations SET archived_at = ? WHERE id = ?",
+      Date.now(),
+      archived,
+    );
+
+    expect(titlesFrom(invokeList({ archiveStatus: "archived" }))).toEqual([
+      "archived-realization",
+    ]);
+  });
+
+  test("the background umbrella is left unnarrowed", () => {
+    // A background row carrying the section's own source is addressed by
+    // conversation type, and narrowing that bucket by source would drop rows
+    // its callers still page through.
+    const background = createConversation({
+      title: "background-realization",
+      conversationType: "background",
+      source: "assistant_initiated",
+    });
+
+    expect(
+      invokeList({ conversationType: "background" }).conversations.map(
+        (c) => c.id,
+      ),
+    ).toContain(background.id);
+  });
+});

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

@@ -13,6 +13,7 @@
 import { z } from "zod";
 
 import { CHANNEL_IDS } from "../../channels/types.js";
+import { isAssistantInitiatedThreadsEnabled } from "../../config/assistant-initiated-threads-gate.js";
 import { channelBindingSchema } from "../../messaging/channel-binding-schema.js";
 import {
   type Confidence,
@@ -35,7 +36,10 @@ import {
   listConversations,
   listPinnedConversations,
 } from "../../persistence/conversation-queries.js";
-import type { ConversationType } from "../../persistence/conversation-types.js";
+import {
+  ASSISTANT_INITIATED_GROUP_ID,
+  type ConversationType,
+} from "../../persistence/conversation-types.js";
 import { getBindingsForConversations } from "../../persistence/external-conversation-store.js";
 import { listGroups } from "../../persistence/group-crud.js";
 import { UserError } from "../../util/errors.js";
@@ -170,9 +174,16 @@ const sectionCountFields = {
  * `chats` is the ungrouped-native bucket. In a view without channel sections
  * the Chats card holds every ungrouped row: the buckets are disjoint, so
  * that reading is `chats` plus the sum of `channel` entries.
+ *
+ * `assistant` is emitted only under the `assistant-initiated-threads` flag,
+ * and while it is emitted its rows are withheld from `chats`, so the
+ * disjointness above holds in both states. A client that does not know the
+ * kind ignores it, which is the same thing an older client does with a
+ * `channel` section for a channel it has no label for.
  */
 const conversationSectionSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("pinned"), ...sectionCountFields }),
+  z.object({ kind: z.literal("assistant"), ...sectionCountFields }),
   z.object({
     kind: z.literal("group"),
     groupId: z.string(),
@@ -274,6 +285,23 @@ function handleListConversations({ queryParams = {} }: RouteHandlerArgs) {
       ? true
       : undefined;
 
+  /* The list half of the section split. A read already scoped to the
+     assistant section obviously keeps its rows; every other standard-listing
+     read withholds them, so they appear in their own section and nowhere
+     else. Confined to `standard`: the background and scheduled buckets are
+     back-compat umbrellas addressed by conversation type, and narrowing them
+     by source would drop rows their callers still page through. Confined to
+     active reads too: the Archive view asks `archiveStatus=archived` with no
+     `groupId`, and the section only ever lists active rows, so withholding
+     there would leave an archived section thread visible nowhere. */
+  const excludeAssistantInitiated =
+    isAssistantInitiatedThreadsEnabled() &&
+    conversationType === "standard" &&
+    archiveStatus === "active" &&
+    groupId !== ASSISTANT_INITIATED_GROUP_ID
+      ? (true as const)
+      : undefined;
+
   const filter: ConversationListFilter = {
     conversationType,
     archiveStatus,
@@ -281,6 +309,7 @@ function handleListConversations({ queryParams = {} }: RouteHandlerArgs) {
     groupId,
     needsAttention,
     foregroundOnly,
+    excludeAssistantInitiated,
   };
   let rows = listConversations({ ...filter, limit, offset });
   const totalCount = countConversations(filter);
@@ -371,10 +400,22 @@ function handleGetUnreadConversationCount() {
  * dangling id is a transient state around group deletion, not a section.
  */
 function handleGetConversationSections() {
-  const counts = countConversationSections();
+  const splitAssistantInitiated = isAssistantInitiatedThreadsEnabled();
+  const counts = countConversationSections({ splitAssistantInitiated });
   const groupsById = new Map(listGroups().map((g) => [g.id, g]));
   const sections: Array<z.infer<typeof conversationSectionSchema>> = [];
 
+  /* Unlike every other section this one renders at zero, the way Chats does:
+     it is where the assistant's own threads accumulate, and a user who has
+     none yet is exactly who the section's empty state is written for. */
+  if (counts.assistantInitiated) {
+    sections.push({
+      kind: "assistant",
+      total: counts.assistantInitiated.total,
+      unread: counts.assistantInitiated.unread,
+    });
+  }
+
   for (const row of counts.groups) {
     if (row.groupId === "system:pinned") {
       sections.push({ kind: "pinned", total: row.total, unread: row.unread });
@@ -655,7 +696,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Sidebar section index",
     description:
-      "One row per renderable sidebar section (Pinned, each non-empty custom group, each origin channel with unassigned conversations, Chats) with total and unread counts and no conversation rows. Lets a client know which sections exist, and what their badges say, without fetching any conversation list. Totals follow the standard listing visibility; unread applies the same rules as GET /v1/conversations/unread-count scoped to the section. Chats is always present, even at zero: it is the leftover bucket and renders regardless.",
+      "One row per renderable sidebar section (Pinned, each non-empty custom group, each origin channel with unassigned conversations, Chats) with total and unread counts and no conversation rows. Lets a client know which sections exist, and what their badges say, without fetching any conversation list. Totals follow the standard listing visibility; unread applies the same rules as GET /v1/conversations/unread-count scoped to the section. Chats is always present, even at zero: it is the leftover bucket and renders regardless. Under the `assistant-initiated-threads` flag an `assistant` section is also present at every count — the threads the assistant started on its own, selectable as a list via `groupId=system:assistant` — and its rows are withheld from Chats so the buckets stay disjoint. With the flag off no `assistant` row is emitted and those conversations are counted in Chats as before.",
     tags: ["conversations"],
     responseBody: conversationSectionsResponseSchema,
     handler: handleGetConversationSections,