@vellumai/assistant 0.12.2 → 0.12.3-staging.2

package/src/persistence/conversation-types.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  COMPUTER_USE_SCREENSHOT_ATTACHMENT_IDS_KEY,
+  computerUseScreenshotAttachmentIdsFromMetadata,
+} from "./conversation-types.js";
+
+describe("computerUseScreenshotAttachmentIdsFromMetadata", () => {
+  test("returns valid nonempty attachment ids", () => {
+    expect(
+      computerUseScreenshotAttachmentIdsFromMetadata({
+        [COMPUTER_USE_SCREENSHOT_ATTACHMENT_IDS_KEY]: [
+          "attachment-1",
+          "",
+          42,
+          "attachment-2",
+        ],
+      }),
+    ).toEqual(["attachment-1", "attachment-2"]);
+  });
+
+  test("treats absent and malformed metadata as legacy", () => {
+    expect(computerUseScreenshotAttachmentIdsFromMetadata(undefined)).toEqual(
+      [],
+    );
+    expect(
+      computerUseScreenshotAttachmentIdsFromMetadata({
+        [COMPUTER_USE_SCREENSHOT_ATTACHMENT_IDS_KEY]: "attachment-1",
+      }),
+    ).toEqual([]);
+  });
+});

package/src/persistence/conversation-types.ts

@@ -82,7 +82,10 @@ 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
@@ -270,6 +273,10 @@ export function isVoiceSessionUserMessage(
  */
 export const SIGHT_FRAME_ATTACHMENT_IDS_KEY = "sightFrameAttachmentIds";
 
+/** Metadata key naming computer-use screenshots automatically linked to a reply. */
+export const COMPUTER_USE_SCREENSHOT_ATTACHMENT_IDS_KEY =
+  "computerUseScreenshotAttachmentIds";
+
 /**
  * The row's attachments that arrived as ambient camera frames, by attachment
  * id. A user attachment carries no metadata of its own, so the marking lives on
@@ -291,6 +298,23 @@ export function sightFrameAttachmentIdsFromMetadata(
   );
 }
 
+/**
+ * Attachment ids whose placement on this row was automatic computer-use
+ * screenshot promotion. Malformed and legacy metadata conservatively yields
+ * no marked attachments.
+ */
+export function computerUseScreenshotAttachmentIdsFromMetadata(
+  metadata: Record<string, unknown> | null | undefined,
+): string[] {
+  const ids = metadata?.[COMPUTER_USE_SCREENSHOT_ATTACHMENT_IDS_KEY];
+  if (!Array.isArray(ids)) {
+    return [];
+  }
+  return ids.filter(
+    (id): id is string => typeof id === "string" && id.length > 0,
+  );
+}
+
 /**
  * True when a stored `messages.metadata` column belongs to a standalone
  * ambient camera keep: a row the call's own gate sampled, which no one spoke.
@@ -360,9 +384,7 @@ export function isDesktopOriginatedUserMessage(
     return false;
   }
   const clientOs = parseClientOs((client as Record<string, unknown>).os);
-  return (
-    clientOs === "macos" || clientOs === "windows" || clientOs === "linux"
-  );
+  return clientOs === "macos" || clientOs === "windows" || clientOs === "linux";
 }
 
 /**

package/src/persistence/llm-usage-store.ts

@@ -515,19 +515,13 @@ interface GroupRow {
 
 type UsageQueryParam = ScheduleAttributionSqlParam;
 
-function normalizeUsageAggregationFilter(
-  filter?: UsageAggregationFilter,
-): UsageAggregationFilter {
-  return normalizeScheduleAttributionFilter(filter);
-}
-
 function buildUsageAggregationWhere(
   range: UsageTimeRange,
   filter?: UsageAggregationFilter,
   eventAlias?: string,
   now: number = Date.now(),
 ): { sql: string; params: UsageQueryParam[] } {
-  const normalized = normalizeUsageAggregationFilter(filter);
+  const normalized = normalizeScheduleAttributionFilter(filter);
   const eventTable = eventAlias ?? "llm_usage_events";
   const createdAt = `${eventTable}.created_at`;
   const clauses = [`${createdAt} >= ? AND ${createdAt} <= ?`];
@@ -852,7 +846,7 @@ export function getUsageGroupBreakdown(
   // Runtime allowlist — defense-in-depth against SQL injection via type assertions.
   assertGroupByDimension(groupBy);
 
-  const normalizedFilter = normalizeUsageAggregationFilter(filter);
+  const normalizedFilter = normalizeScheduleAttributionFilter(filter);
 
   // Conversation grouping requires a JOIN with conversations to resolve titles.
   if (groupBy === "conversation") {
@@ -984,7 +978,7 @@ export function getUsageGroupedSeries(
     throw new Error("Grouped usage series does not support conversation");
   }
 
-  const normalizedFilter = normalizeUsageAggregationFilter(filter);
+  const normalizedFilter = normalizeScheduleAttributionFilter(filter);
   let rows: UsageGroupedBucketRow[];
 
   if (groupBy === "schedule") {

package/src/persistence/message-metadata.ts

@@ -1,3 +1,4 @@
+import { type ModeSession, parseModeSession } from "../api/mode-session.js";
 import { safeParseRecord } from "../util/json.js";
 
 /**
@@ -18,3 +19,27 @@ export function mergeMessageMetadata(
     ...updates,
   });
 }
+
+export function readModeSessionMetadata(
+  metadata: string | null | undefined,
+): ModeSession | undefined {
+  if (!metadata) {
+    return undefined;
+  }
+  return parseModeSession(safeParseRecord(metadata).modeSession);
+}
+
+export function readMessageSentAt(
+  metadata: string | null | undefined,
+): number | undefined {
+  if (!metadata) {
+    return undefined;
+  }
+  const sentAt = safeParseRecord(metadata).sentAt;
+  return typeof sentAt === "number" &&
+    Number.isInteger(sentAt) &&
+    sentAt >= 0 &&
+    Number.isFinite(new Date(sentAt).getTime())
+    ? sentAt
+    : undefined;
+}

package/src/persistence/migrations/378-create-conversation-tool-surfaces.test.ts

@@ -0,0 +1,78 @@
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import * as schema from "../schema.js";
+import { migrateCreateConversationToolSurfaces } from "./378-create-conversation-tool-surfaces.js";
+
+function createTestDb() {
+  const sqlite = new Database(":memory:");
+  sqlite.run("PRAGMA foreign_keys = ON");
+  // Only the parent table the FK points at.
+  sqlite.run(/*sql*/ `CREATE TABLE conversations (id TEXT PRIMARY KEY)`);
+  return { sqlite, db: drizzle(sqlite, { schema }) };
+}
+
+function tableDdl(sqlite: Database): string | undefined {
+  const row = sqlite
+    .query(
+      `SELECT sql FROM sqlite_master WHERE type='table' AND name='conversation_tool_surfaces'`,
+    )
+    .get() as { sql: string } | null;
+  return row?.sql;
+}
+
+function insertSurface(sqlite: Database, conversationId: string): void {
+  sqlite
+    .query(
+      /*sql*/ `INSERT INTO conversation_tool_surfaces (conversation_id, tools_json, tools_hash, updated_at) VALUES (?, ?, ?, ?)`,
+    )
+    .run(conversationId, "[]", "hash", 1);
+}
+
+function surfaceCount(sqlite: Database): number {
+  const row = sqlite
+    .query(`SELECT COUNT(*) AS n FROM conversation_tool_surfaces`)
+    .get() as { n: number };
+  return row.n;
+}
+
+describe("migration 378: conversation_tool_surfaces", () => {
+  test("creates the table keyed by conversation with a cascading FK", () => {
+    const { sqlite, db } = createTestDb();
+    expect(tableDdl(sqlite)).toBeUndefined();
+
+    migrateCreateConversationToolSurfaces(db);
+
+    const ddl = tableDdl(sqlite);
+    expect(ddl).toContain("conversation_id TEXT PRIMARY KEY");
+    expect(ddl).toContain("REFERENCES conversations(id) ON DELETE CASCADE");
+    expect(ddl).toContain("tools_json TEXT NOT NULL");
+    expect(ddl).toContain("tools_hash TEXT NOT NULL");
+    expect(ddl).toContain("updated_at INTEGER NOT NULL");
+  });
+
+  test("deleting a conversation cascades to its surface row", () => {
+    const { sqlite, db } = createTestDb();
+    migrateCreateConversationToolSurfaces(db);
+    sqlite.query(`INSERT INTO conversations (id) VALUES (?)`).run("conv-1");
+    insertSurface(sqlite, "conv-1");
+    expect(surfaceCount(sqlite)).toBe(1);
+
+    sqlite.query(`DELETE FROM conversations WHERE id = ?`).run("conv-1");
+
+    expect(surfaceCount(sqlite)).toBe(0);
+  });
+
+  test("is idempotent: a second run keeps the table and its rows", () => {
+    const { sqlite, db } = createTestDb();
+    migrateCreateConversationToolSurfaces(db);
+    sqlite.query(`INSERT INTO conversations (id) VALUES (?)`).run("conv-1");
+    insertSurface(sqlite, "conv-1");
+
+    expect(() => migrateCreateConversationToolSurfaces(db)).not.toThrow();
+
+    expect(surfaceCount(sqlite)).toBe(1);
+  });
+});

package/src/persistence/migrations/378-create-conversation-tool-surfaces.ts

@@ -0,0 +1,29 @@
+import type { DrizzleDb } from "../db-connection.js";
+
+const TABLE = "conversation_tool_surfaces";
+
+/**
+ * Create `conversation_tool_surfaces`: one row per conversation holding the
+ * tool definitions its most recent live turn sent to the provider, keyed by
+ * conversation with a content hash so an unchanged surface is never rewritten.
+ *
+ * Its own table rather than a column on `conversations` because the payload
+ * is a JSON array of every tool definition (tens of kilobytes) that only fork
+ * wakes read, while `conversations` rows are read whole on every hot path.
+ * The row cascades with its conversation, so a deleted conversation leaves
+ * no surface behind.
+ *
+ * Idempotent via IF NOT EXISTS.
+ */
+export function migrateCreateConversationToolSurfaces(
+  database: DrizzleDb,
+): void {
+  database.run(
+    `CREATE TABLE IF NOT EXISTS ${TABLE} (
+       conversation_id TEXT PRIMARY KEY REFERENCES conversations(id) ON DELETE CASCADE,
+       tools_json TEXT NOT NULL,
+       tools_hash TEXT NOT NULL,
+       updated_at INTEGER NOT NULL
+     )`,
+  );
+}

package/src/persistence/migrations/379-oauth-providers-response-ok-field.test.ts

@@ -0,0 +1,92 @@
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import * as schema from "../schema.js";
+import { migrateOAuthProvidersResponseOkField } from "./379-oauth-providers-response-ok-field.js";
+
+function createTestDb(options: { withTable?: boolean } = {}) {
+  const sqlite = new Database(":memory:");
+  if (options.withTable !== false) {
+    // Pre-379 shape: only the columns the migration and tests touch.
+    sqlite.exec(/*sql*/ `
+      CREATE TABLE oauth_providers (
+        provider_key TEXT PRIMARY KEY,
+        identity_ok_field TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+    `);
+  }
+  return { sqlite, db: drizzle(sqlite, { schema }) };
+}
+
+function columnNames(sqlite: Database): string[] {
+  return (
+    sqlite.query("PRAGMA table_info(oauth_providers)").all() as Array<{
+      name: string;
+    }>
+  ).map((c) => c.name);
+}
+
+describe("migration 379: oauth_providers.response_ok_field", () => {
+  test("adds the nullable column beside the identity one", () => {
+    const { sqlite, db } = createTestDb();
+    expect(columnNames(sqlite)).not.toContain("response_ok_field");
+
+    migrateOAuthProvidersResponseOkField(db);
+
+    const column = (
+      sqlite.query("PRAGMA table_info(oauth_providers)").all() as Array<{
+        name: string;
+        notnull: number;
+      }>
+    ).find((c) => c.name === "response_ok_field");
+    expect(column).toBeDefined();
+    expect(column?.notnull).toBe(0);
+    expect(columnNames(sqlite)).toContain("identity_ok_field");
+  });
+
+  test("rows written before the column existed read back null", () => {
+    // A provider that declared nothing is judged by status alone, which is
+    // what it was before the column existed.
+    const { sqlite, db } = createTestDb();
+    sqlite.exec(/*sql*/ `
+      INSERT INTO oauth_providers (provider_key, identity_ok_field, created_at, updated_at)
+      VALUES ('slack', 'ok', 1000, 1000)
+    `);
+
+    migrateOAuthProvidersResponseOkField(db);
+
+    const row = sqlite
+      .query(
+        "SELECT response_ok_field FROM oauth_providers WHERE provider_key = 'slack'",
+      )
+      .get() as { response_ok_field: unknown };
+    expect(row.response_ok_field).toBeNull();
+  });
+
+  test("is idempotent: re-run is a no-op", () => {
+    const { sqlite, db } = createTestDb();
+
+    migrateOAuthProvidersResponseOkField(db);
+    expect(() => migrateOAuthProvidersResponseOkField(db)).not.toThrow();
+
+    expect(
+      columnNames(sqlite).filter((n) => n === "response_ok_field"),
+    ).toHaveLength(1);
+  });
+
+  test("a missing table is a failure, never a silent success", () => {
+    // The runner checkpoints a throwing step as failed and retries it, and
+    // the registry defers this step behind the table's own. Swallowing the
+    // error here would checkpoint the step as done against no table, and the
+    // column would never be added.
+    // The driver wraps SQLite's "no such table" in its own message, so the
+    // assertion is that the step throws at all.
+    const { db } = createTestDb({ withTable: false });
+
+    expect(() => migrateOAuthProvidersResponseOkField(db)).toThrow();
+  });
+});

package/src/persistence/migrations/379-oauth-providers-response-ok-field.ts

@@ -0,0 +1,32 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
+
+const TABLE_NAME = "oauth_providers";
+const COLUMN_NAME = "response_ok_field";
+const COLUMN_DEFINITION = "response_ok_field TEXT";
+
+/**
+ * Add `response_ok_field` to `oauth_providers` (migration 149): the dot path
+ * of the boolean a provider's API puts in every response body to report
+ * success (Slack: `ok`). Its own column, distinct from `identity_ok_field`,
+ * because the two declare different facts: the identity field governs the
+ * one call the provider row names, this one governs any request made with
+ * the credential.
+ *
+ * Nullable with no backfill: seeding upserts the value for the built-in rows
+ * on the next start, and a custom provider that declares nothing is judged by
+ * status alone, which is what it was before the column existed.
+ *
+ * Idempotent: guarded with `tableHasColumn` so a crash between the `ALTER
+ * TABLE` and the checkpoint write doesn't cause a duplicate-column error on
+ * the next boot. A missing table is not swallowed: the registry declares the
+ * dependency on the table's own step, so this one is deferred rather than
+ * checkpointed as done against no table.
+ */
+export function migrateOAuthProvidersResponseOkField(
+  database: DrizzleDb,
+): void {
+  if (!tableHasColumn(database, TABLE_NAME, COLUMN_NAME)) {
+    database.run(`ALTER TABLE ${TABLE_NAME} ADD COLUMN ${COLUMN_DEFINITION}`);
+  }
+}

package/src/persistence/migrations/380-conversation-tool-surfaces-delegate-independent-tasks.test.ts

@@ -0,0 +1,90 @@
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import * as schema from "../schema.js";
+import { migrateCreateConversationToolSurfaces } from "./378-create-conversation-tool-surfaces.js";
+import { migrateConversationToolSurfacesDelegateIndependentTasks } from "./380-conversation-tool-surfaces-delegate-independent-tasks.js";
+
+function createTestDb(options: { withTable?: boolean } = {}) {
+  const sqlite = new Database(":memory:");
+  sqlite.run("PRAGMA foreign_keys = ON");
+  // Only the parent table the FK points at.
+  sqlite.run(/*sql*/ `CREATE TABLE conversations (id TEXT PRIMARY KEY)`);
+  const db = drizzle(sqlite, { schema });
+  if (options.withTable !== false) {
+    // Pre-380 shape: the table as migration 378 creates it.
+    migrateCreateConversationToolSurfaces(db);
+  }
+  return { sqlite, db };
+}
+
+function columns(sqlite: Database): Array<{ name: string; notnull: number }> {
+  return sqlite
+    .query("PRAGMA table_info(conversation_tool_surfaces)")
+    .all() as Array<{ name: string; notnull: number }>;
+}
+
+describe("migration 380: conversation_tool_surfaces.delegate_independent_tasks", () => {
+  test("adds the nullable column", () => {
+    const { sqlite, db } = createTestDb();
+    expect(columns(sqlite).map((c) => c.name)).not.toContain(
+      "delegate_independent_tasks",
+    );
+
+    migrateConversationToolSurfacesDelegateIndependentTasks(db);
+
+    const column = columns(sqlite).find(
+      (c) => c.name === "delegate_independent_tasks",
+    );
+    expect(column).toBeDefined();
+    expect(column?.notnull).toBe(0);
+  });
+
+  test("rows written before the column existed read back null", () => {
+    // A fork replaying such a row derives the section for itself, which is
+    // what it did before the column existed.
+    const { sqlite, db } = createTestDb();
+    sqlite.query(`INSERT INTO conversations (id) VALUES (?)`).run("conv-1");
+    sqlite
+      .query(
+        /*sql*/ `INSERT INTO conversation_tool_surfaces (conversation_id, tools_json, tools_hash, updated_at) VALUES (?, ?, ?, ?)`,
+      )
+      .run("conv-1", "[]", "hash", 1);
+
+    migrateConversationToolSurfacesDelegateIndependentTasks(db);
+
+    const row = sqlite
+      .query(
+        "SELECT delegate_independent_tasks FROM conversation_tool_surfaces WHERE conversation_id = 'conv-1'",
+      )
+      .get() as { delegate_independent_tasks: unknown };
+    expect(row.delegate_independent_tasks).toBeNull();
+  });
+
+  test("is idempotent: re-run is a no-op", () => {
+    const { sqlite, db } = createTestDb();
+
+    migrateConversationToolSurfacesDelegateIndependentTasks(db);
+    expect(() =>
+      migrateConversationToolSurfacesDelegateIndependentTasks(db),
+    ).not.toThrow();
+
+    expect(
+      columns(sqlite).filter((c) => c.name === "delegate_independent_tasks"),
+    ).toHaveLength(1);
+  });
+
+  test("a missing table is a failure, never a silent success", () => {
+    // The runner checkpoints a throwing step as failed and retries it, and
+    // the registry defers this step behind the table's own. Swallowing the
+    // error here would checkpoint the step as done against no table, and the
+    // column would never be added.
+    const { db } = createTestDb({ withTable: false });
+
+    expect(() =>
+      migrateConversationToolSurfacesDelegateIndependentTasks(db),
+    ).toThrow();
+  });
+});

package/src/persistence/migrations/380-conversation-tool-surfaces-delegate-independent-tasks.ts

@@ -0,0 +1,34 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
+
+const TABLE_NAME = "conversation_tool_surfaces";
+const COLUMN_NAME = "delegate_independent_tasks";
+const COLUMN_DEFINITION = "delegate_independent_tasks INTEGER";
+
+/**
+ * Add `delegate_independent_tasks` to `conversation_tool_surfaces`: whether
+ * the system prompt of the turn that recorded the surface rendered the
+ * parallel-delegation section (`01-parallel-tasks`). The prompt derives that
+ * section from the same resolved tool surface, so a fork wake replaying the
+ * surface needs the rendered state too: the section sits in the system
+ * prompt, the second tier of the provider cache prefix, and a fork that
+ * derives it from its own restricted scope renders it off where the source
+ * rendered it on, missing the source's cached prefix from that byte on.
+ *
+ * Nullable with no backfill: a row written before the column existed reads
+ * null and the fork derives the section for itself, exactly as it did before
+ * the column; the next live turn records the state.
+ *
+ * Idempotent: guarded with `tableHasColumn` so a crash between the `ALTER
+ * TABLE` and the checkpoint write doesn't cause a duplicate-column error on
+ * the next boot. A missing table is not swallowed: the registry declares the
+ * dependency on the table's own step, so this one is deferred rather than
+ * checkpointed as done against no table.
+ */
+export function migrateConversationToolSurfacesDelegateIndependentTasks(
+  database: DrizzleDb,
+): void {
+  if (!tableHasColumn(database, TABLE_NAME, COLUMN_NAME)) {
+    database.run(`ALTER TABLE ${TABLE_NAME} ADD COLUMN ${COLUMN_DEFINITION}`);
+  }
+}

package/src/persistence/migrations/381-create-conversation-mode-sessions.ts

@@ -0,0 +1,41 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+const TABLE = "conversation_mode_sessions";
+
+export function migrateCreateConversationModeSessions(
+  database: DrizzleDb,
+): void {
+  const sqlite = getSqliteFrom(database);
+  sqlite.exec(/* sql */ `
+    CREATE TABLE IF NOT EXISTS ${TABLE} (
+      id TEXT PRIMARY KEY,
+      conversation_id TEXT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+      mode TEXT NOT NULL CHECK (mode IN ('computer_use', 'browser', 'live_vision', 'ambient')),
+      status TEXT NOT NULL CHECK (status IN ('active', 'completed', 'interrupted')),
+      source_started_at INTEGER NOT NULL,
+      first_included_at INTEGER,
+      first_included_message_id TEXT,
+      last_activity_at INTEGER NOT NULL,
+      last_owned_message_id TEXT,
+      ended_at INTEGER,
+      end_reason TEXT,
+      revision INTEGER NOT NULL DEFAULT 1 CHECK (revision > 0),
+      CHECK ((first_included_at IS NULL) = (first_included_message_id IS NULL)),
+      CHECK (
+        (status = 'active' AND ended_at IS NULL AND end_reason IS NULL)
+        OR (status = 'completed' AND ended_at IS NOT NULL AND end_reason IS NOT NULL AND length(end_reason) > 0)
+        OR (status = 'interrupted' AND end_reason IS NOT NULL AND length(end_reason) > 0)
+      ),
+      CHECK (ended_at IS NULL OR ended_at >= last_activity_at),
+      CHECK (last_activity_at >= source_started_at),
+      CHECK (first_included_at IS NULL OR first_included_at <= last_activity_at)
+    );
+    CREATE INDEX IF NOT EXISTS idx_conversation_mode_sessions_conversation_status
+      ON ${TABLE} (conversation_id, status);
+  `);
+}
+
+export function downCreateConversationModeSessions(database: DrizzleDb): void {
+  getSqliteFrom(database).exec(`DROP TABLE IF EXISTS ${TABLE}`);
+}

package/src/persistence/migrations/382-create-client-connection-events.ts

@@ -0,0 +1,40 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+const TABLE = "client_connection_events";
+
+/**
+ * Create `client_connection_events`: the durable hub subscribe/dispose
+ * ledger used by `assistant clients history`.
+ *
+ * One row per client-subscriber lifecycle event. Reconnects shorter than
+ * the flap window are coalesced at read time, not at write time, so the
+ * raw event stream stays a complete audit.
+ *
+ * Idempotent via IF NOT EXISTS.
+ */
+export function migrateCreateClientConnectionEvents(database: DrizzleDb): void {
+  const sqlite = getSqliteFrom(database);
+  sqlite.exec(
+    `CREATE TABLE IF NOT EXISTS ${TABLE} (
+       id TEXT PRIMARY KEY,
+       client_id TEXT NOT NULL,
+       interface_id TEXT NOT NULL,
+       connection_id TEXT NOT NULL,
+       reason TEXT NOT NULL,
+       occurred_at INTEGER NOT NULL,
+       actor_principal_id TEXT,
+       client_version TEXT,
+       sse_watchdog INTEGER,
+       machine_name TEXT
+     )`,
+  );
+  sqlite.exec(
+    `CREATE INDEX IF NOT EXISTS idx_client_connection_events_client_occurred
+       ON ${TABLE} (client_id, occurred_at)`,
+  );
+  sqlite.exec(
+    `CREATE INDEX IF NOT EXISTS idx_client_connection_events_occurred
+       ON ${TABLE} (occurred_at)`,
+  );
+}

package/src/persistence/migrations/__tests__/382-create-client-connection-events.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Migration 382 creates `client_connection_events`, the durable hub
+ * subscribe/dispose ledger used by `assistant clients history`.
+ */
+
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import { getSqliteFrom } from "../../db-connection.js";
+import * as schema from "../../schema.js";
+import { migrateCreateClientConnectionEvents } from "../382-create-client-connection-events.js";
+
+function createTestDb() {
+  const sqlite = new Database(":memory:");
+  sqlite.exec("PRAGMA journal_mode=WAL");
+  return drizzle(sqlite, { schema });
+}
+
+function tableNames(db: ReturnType<typeof createTestDb>): string[] {
+  const rows = getSqliteFrom(db)
+    .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
+    .all() as { name: string }[];
+  return rows.map((row) => row.name);
+}
+
+function indexNames(db: ReturnType<typeof createTestDb>): string[] {
+  const rows = getSqliteFrom(db)
+    .prepare("SELECT name FROM sqlite_master WHERE type = 'index'")
+    .all() as { name: string }[];
+  return rows.map((row) => row.name);
+}
+
+describe("migrateCreateClientConnectionEvents", () => {
+  test("creates the table and its lookup indexes", () => {
+    const db = createTestDb();
+
+    migrateCreateClientConnectionEvents(db);
+
+    expect(tableNames(db)).toContain("client_connection_events");
+    expect(indexNames(db)).toContain(
+      "idx_client_connection_events_client_occurred",
+    );
+    expect(indexNames(db)).toContain("idx_client_connection_events_occurred");
+  });
+
+  test("re-running is a no-op", () => {
+    const db = createTestDb();
+
+    migrateCreateClientConnectionEvents(db);
+    migrateCreateClientConnectionEvents(db);
+
+    expect(tableNames(db)).toContain("client_connection_events");
+  });
+});