@vellumai/assistant 0.7.3 → 0.8.1

package/src/memory/memory-retrospective-trigger-check.ts

@@ -0,0 +1,91 @@
+// ---------------------------------------------------------------------------
+// Memory retrospective — periodic trigger check.
+// ---------------------------------------------------------------------------
+//
+// Called from post-turn hooks (after each agent turn completes). Decides
+// whether to enqueue a retrospective for this conversation based on:
+//
+//   1. Cooldown gate: never within `minCooldownMs` of the last attempt
+//      (success or failure). Prevents tight retry loops across trigger
+//      types.
+//   2. Interval threshold: time since last attempt >= `timeThresholdMs`.
+//   3. Message count threshold: new messages since `lastProcessedMessageId`
+//      >= `messageThreshold`.
+//
+// First-run case (no state row) skips the cooldown — `lastRunAt = 0` so the
+// gap is effectively `Infinity`. The interval threshold trips immediately;
+// the message-count threshold trips once enough messages accumulate.
+
+import type { AssistantConfig } from "../config/types.js";
+import { getLogger } from "../util/logger.js";
+import { countMessagesAfter } from "./conversation-crud.js";
+import { enqueueMemoryRetrospectiveIfEnabled } from "./memory-retrospective-enqueue.js";
+import { getRetrospectiveState } from "./memory-retrospective-state.js";
+
+const log = getLogger("memory-retrospective-trigger-check");
+
+export type RetrospectiveTrigger = "interval" | "message_count";
+
+/**
+ * Returns the trigger kind that fired, or `null` if no threshold tripped.
+ * Exported separately from `maybeEnqueueRetrospective` so tests can assert on
+ * the decision without observing side effects.
+ */
+export function shouldEnqueueRetrospective(args: {
+  state: { lastProcessedMessageId: string; lastRunAt: number } | null;
+  newMessageCount: number;
+  now: number;
+  timeThresholdMs: number;
+  messageThreshold: number;
+  minCooldownMs: number;
+}): RetrospectiveTrigger | null {
+  const {
+    state,
+    newMessageCount,
+    now,
+    timeThresholdMs,
+    messageThreshold,
+    minCooldownMs,
+  } = args;
+
+  if (state && now - state.lastRunAt < minCooldownMs) return null;
+
+  if (state && now - state.lastRunAt >= timeThresholdMs) return "interval";
+  if (!state) return "interval";
+
+  if (newMessageCount >= messageThreshold) return "message_count";
+  return null;
+}
+
+/**
+ * Post-turn hook entry point. Looks up state, counts new messages, evaluates
+ * thresholds, and enqueues if appropriate. Best-effort — any thrown error is
+ * caught and logged so the agent turn cleanup path doesn't fail.
+ */
+export function maybeEnqueueRetrospective(
+  conversationId: string,
+  config: AssistantConfig,
+): void {
+  try {
+    const state = getRetrospectiveState(conversationId);
+    const newMessageCount = countMessagesAfter(
+      conversationId,
+      state?.lastProcessedMessageId ?? null,
+    );
+    if (newMessageCount === 0) return;
+
+    const trigger = shouldEnqueueRetrospective({
+      state,
+      newMessageCount,
+      now: Date.now(),
+      timeThresholdMs: config.memory.retrospective.timeThresholdMs,
+      messageThreshold: config.memory.retrospective.messageThreshold,
+      minCooldownMs: config.memory.retrospective.minCooldownMs,
+    });
+    if (!trigger) return;
+
+    enqueueMemoryRetrospectiveIfEnabled({ conversationId, trigger });
+  } catch (err) {
+    log.warn({ err, conversationId }, "trigger-check failed; skipping enqueue");
+  }
+}

package/src/memory/memory-v2-activation-log-store.ts

@@ -39,8 +39,43 @@ export interface MemoryV2ConceptRowRecord {
    */
   inRerankPool: boolean;
   spreadContribution: number;
-  source: "prior_state" | "ann_top50" | "both";
-  status: "in_context" | "injected" | "not_injected" | "page_missing";
+  /**
+   * Provenance of this concept row.
+   *   - `prior_state` — carried over from prior turn's activation state.
+   *   - `ann_top50`   — entered via ANN top-K candidate pool.
+   *   - `both`        — present in both prior state and ANN pool.
+   *   - `router`      — selected by the Sonnet router (memory-v2 router
+   *     mode). Router-mode rows zero out all activation values
+   *     (`finalActivation`, `ownActivation`, `priorActivation`, channel
+   *     similarities, rerank boosts, `spreadContribution`) because the
+   *     router does not compute spreading-activation scores.
+   *   - `carry_over`  — router-mode row representing a slug carried over
+   *     from `priorEverInjected` that the router did NOT re-pick on this
+   *     turn. The cached attachment from a prior turn is still present
+   *     on a prior user message; emitting `source: "router"` for these
+   *     rows would overcount router selections in inspector queries.
+   *     Same zeroed activation values as `router`.
+   */
+  source: "prior_state" | "ann_top50" | "both" | "router" | "carry_over";
+  /**
+   * Per-turn outcome for this slug:
+   *   - `in_context`  — already injected on a prior turn; cached attachment
+   *     remains visible without re-rendering.
+   *   - `injected`    — freshly rendered into this turn's user message.
+   *   - `not_injected`— a candidate that didn't make `slugsToRender`.
+   *   - `page_missing`— would-have-been-injected, but `readPage` returned
+   *     null (file vanished between selection and render — stale Qdrant
+   *     or edge-index entry).
+   *   - `corrupt`     — would-have-been-injected, but `readPage` threw
+   *     (e.g. malformed frontmatter). Other slugs in the same batch
+   *     rendered normally.
+   */
+  status:
+    | "in_context"
+    | "injected"
+    | "not_injected"
+    | "page_missing"
+    | "corrupt";
 }
 
 export interface MemoryV2ConfigSnapshot {
@@ -57,7 +92,16 @@ export interface MemoryV2ConfigSnapshot {
 export interface RecordMemoryV2ActivationLogParams {
   conversationId: string;
   turn: number;
-  mode: "context-load" | "per-turn";
+  /**
+   * Call-site mode: `context-load` for fresh / post-compaction loads,
+   * `per-turn` for normal append injections, `errored` when `injectMemoryV2Block`
+   * threw before completing — telemetry is still written so silent failures
+   * are observable in the database, with whatever `concepts` rows had been
+   * built so far (possibly empty). `router` indicates the Sonnet
+   * router selected the per-turn page set; router-mode rows carry zeroed
+   * activation values and `source: "router"` on every concept row.
+   */
+  mode: "context-load" | "per-turn" | "errored" | "router";
   concepts: MemoryV2ConceptRowRecord[];
   config: MemoryV2ConfigSnapshot;
 }
@@ -105,7 +149,7 @@ export function backfillMemoryV2ActivationMessageId(
 export interface MemoryV2ActivationLog {
   conversationId: string;
   turn: number;
-  mode: "context-load" | "per-turn";
+  mode: "context-load" | "per-turn" | "errored" | "router";
   concepts: MemoryV2ConceptRowRecord[];
   config: MemoryV2ConfigSnapshot;
 }
@@ -126,7 +170,7 @@ export function getMemoryV2ActivationLogByMessageIds(
   return {
     conversationId: row.conversationId,
     turn: row.turn,
-    mode: row.mode as "context-load" | "per-turn",
+    mode: row.mode as "context-load" | "per-turn" | "errored" | "router",
     concepts: JSON.parse(row.conceptsJson) as MemoryV2ConceptRowRecord[],
     config: JSON.parse(row.configJson) as MemoryV2ConfigSnapshot,
   };

package/src/memory/memory-v2-concept-frequency.ts

@@ -52,6 +52,7 @@ const ZERO_COUNTS: ConceptFrequencyCounts = {
   in_context: 0,
   not_injected: 0,
   page_missing: 0,
+  corrupt: 0,
 };
 
 interface CountRow {
@@ -130,6 +131,9 @@ export async function getConceptFrequencySummary(
       case "page_missing":
         entry.counts.page_missing += row.count;
         break;
+      case "corrupt":
+        entry.counts.corrupt += row.count;
+        break;
       default:
         // Forward-compat: unknown status values are ignored, not summed into
         // totalEvaluations. The activation pipeline produces a closed enum.

package/src/memory/message-content.ts

@@ -121,7 +121,6 @@ export function extractMediaBlockMeta(
   }
 }
 
-
 function stableJson(value: unknown): string {
   try {
     return JSON.stringify(value);
@@ -129,3 +128,41 @@ function stableJson(value: unknown): string {
     return "<unserializable />";
   }
 }
+
+/**
+ * Coerce stored message content into a single human-readable text string,
+ * dropping non-text blocks (images, tool calls, tool results, thinking,
+ * …). Used by call sites that want only the spoken text — sweep-model
+ * context, RAG backfill, bookmark previews. For richer renderings that
+ * include tool metadata, use {@link extractTextFromStoredMessageContent}
+ * instead.
+ *
+ * Handles the two on-disk shapes:
+ *   - Modern rows: JSON-serialized `ContentBlock[]`
+ *   - Legacy rows: plain string
+ *
+ * Parse failures fall back to returning the raw input trimmed (the
+ * legacy-string path).
+ */
+export function stringifyMessageContent(stored: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stored);
+  } catch {
+    return stored.trim();
+  }
+  if (typeof parsed === "string") return parsed.trim();
+  if (!Array.isArray(parsed)) return "";
+  const parts: string[] = [];
+  for (const block of parsed) {
+    if (
+      block &&
+      typeof block === "object" &&
+      (block as { type?: string }).type === "text" &&
+      typeof (block as { text?: unknown }).text === "string"
+    ) {
+      parts.push((block as { text: string }).text);
+    }
+  }
+  return parts.join("\n").trim();
+}

package/src/memory/migrations/227-add-conversation-inference-profile.ts

@@ -8,8 +8,13 @@ export function migrateAddConversationInferenceProfile(
   const columns = raw.query(`PRAGMA table_info(conversations)`).all() as Array<{
     name: string;
   }>;
+  // Skip if either the original camelCase column or the renamed snake_case
+  // column from migration 228 is already present. Without the snake_case
+  // check, this migration would re-add the camelCase column on every boot
+  // after 228 runs, leaving both columns permanently.
   const hasColumn = columns.some(
-    (column) => column.name === "inferenceProfile",
+    (column) =>
+      column.name === "inferenceProfile" || column.name === "inference_profile",
   );
   if (hasColumn) {
     return;

package/src/memory/migrations/228-rename-inference-profile-snake-case.ts

@@ -6,19 +6,32 @@ import { tableHasColumn } from "./schema-introspection.js";
  * by migration 227) to `inference_profile` so it matches the snake_case
  * convention used by every other column on the table.
  *
- * Idempotent:
- * - camelCase column present, snake_case absent → renames it.
- * - snake_case column already present → no-op.
- * - neither column present → no-op (shouldn't happen since 227 ran first,
- *   but we guard for completeness).
+ * Idempotent and self-healing:
+ * - both columns present → drop the camelCase one (heals instances that
+ *   already booted twice with the original buggy migration 227, where 227
+ *   re-added the camelCase column after this migration renamed it).
+ * - camelCase column present, snake_case absent → rename it.
+ * - snake_case column present, camelCase absent → no-op.
+ * - neither column present → no-op.
  */
 export function migrateRenameInferenceProfileSnakeCase(
   database: DrizzleDb,
 ): void {
-  if (tableHasColumn(database, "conversations", "inference_profile")) {
+  const hasSnake = tableHasColumn(
+    database,
+    "conversations",
+    "inference_profile",
+  );
+  const hasCamel = tableHasColumn(
+    database,
+    "conversations",
+    "inferenceProfile",
+  );
+  if (hasSnake && hasCamel) {
+    database.run(`ALTER TABLE conversations DROP COLUMN inferenceProfile`);
     return;
   }
-  if (!tableHasColumn(database, "conversations", "inferenceProfile")) {
+  if (!hasCamel) {
     return;
   }
   database.run(

package/src/memory/migrations/229-delete-private-conversations.test.ts

@@ -615,7 +615,8 @@ function seedGuardianAndApprovalRows(raw: Database, now: number): void {
       created_at,
       updated_at
     ) VALUES
-      ('call-standard-guardian', 'conv-standard', 'test-provider', '+15550100', '+15550101', 'initiated', ${now}, ${now});
+      ('call-standard-guardian', 'conv-standard', 'test-provider', '+15550100', '+15550101', 'initiated', ${now}, ${now}),
+      ('call-private-guardian', 'conv-private', 'test-provider', '+15550102', '+15550103', 'initiated', ${now}, ${now});
 
     INSERT INTO call_pending_questions (
       id,
@@ -708,6 +709,23 @@ function seedGuardianAndApprovalRows(raw: Database, now: number): void {
       ('scoped-grant-standard', 'request_id', 'canonical-request-standard', NULL, NULL, 'vellum', 'vellum', 'conv-standard', 'active', ${now + 60000}, ${now}, ${now}),
       ('scoped-grant-unscoped', 'tool_signature', NULL, 'test_tool', 'digest-123', 'vellum', 'vellum', NULL, 'active', ${now + 60000}, ${now}, ${now});
 
+    INSERT INTO scoped_approval_grants (
+      id,
+      scope_mode,
+      request_id,
+      tool_name,
+      input_digest,
+      request_channel,
+      decision_channel,
+      conversation_id,
+      call_session_id,
+      status,
+      expires_at,
+      created_at,
+      updated_at
+    ) VALUES
+      ('scoped-grant-private-call-only', 'tool_signature', NULL, 'test_tool', 'digest-456', 'vellum', 'vellum', NULL, 'call-private-guardian', 'active', ${now + 60000}, ${now}, ${now});
+
     INSERT INTO channel_guardian_approval_requests (
       id,
       run_id,
@@ -1034,6 +1052,13 @@ describe("migrateDeletePrivateConversations", () => {
     expect(
       countWhere(raw, "scoped_approval_grants", `id = 'scoped-grant-unscoped'`),
     ).toBe(1);
+    expect(
+      countWhere(
+        raw,
+        "scoped_approval_grants",
+        `id = 'scoped-grant-private-call-only'`,
+      ),
+    ).toBe(0);
     expect(
       countWhere(
         raw,
@@ -1084,4 +1109,48 @@ describe("migrateDeletePrivateConversations", () => {
       ),
     ).toBe(1);
   });
+
+  test("removes orphan attachments left by prior runs that deleted private messages", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+    const now = Date.now();
+
+    bootstrapTables(raw);
+    seedConversation(raw, "conv-standard", "standard");
+    raw.exec(/*sql*/ `
+      INSERT INTO attachments (
+        id,
+        original_filename,
+        mime_type,
+        size_bytes,
+        kind,
+        data_base64,
+        created_at
+      ) VALUES (
+        'orphan-private-attachment',
+        'leaked.txt',
+        'text/plain',
+        1,
+        'text',
+        'eA==',
+        ${now}
+      );
+    `);
+
+    expect(
+      countWhere(raw, "attachments", `id = 'orphan-private-attachment'`),
+    ).toBe(1);
+    expect(
+      countWhere(raw, "attachments", `id = 'conv-standard-attachment'`),
+    ).toBe(1);
+
+    migrateDeletePrivateConversations(db);
+
+    expect(
+      countWhere(raw, "attachments", `id = 'orphan-private-attachment'`),
+    ).toBe(0);
+    expect(
+      countWhere(raw, "attachments", `id = 'conv-standard-attachment'`),
+    ).toBe(1);
+  });
 });

package/src/memory/migrations/229-delete-private-conversations.ts

@@ -47,6 +47,10 @@ export function migrateDeletePrivateConversations(database: DrizzleDb): void {
   database.run(/*sql*/ `
     DELETE FROM scoped_approval_grants
     WHERE conversation_id IN (${PRIVATE_CONVERSATION_IDS})
+       OR call_session_id IN (
+        SELECT id FROM call_sessions
+        WHERE conversation_id IN (${PRIVATE_CONVERSATION_IDS})
+      )
   `);
   database.run(/*sql*/ `
     DELETE FROM guardian_action_deliveries
@@ -193,6 +197,14 @@ export function migrateDeletePrivateConversations(database: DrizzleDb): void {
     DELETE FROM messages
     WHERE conversation_id IN (${PRIVATE_CONVERSATION_IDS})
   `);
+  database.run(/*sql*/ `
+    DELETE FROM attachments
+    WHERE NOT EXISTS (
+      SELECT 1
+      FROM message_attachments ma
+      WHERE ma.attachment_id = attachments.id
+    )
+  `);
   database.run(/*sql*/ `
     DELETE FROM memory_summaries
     WHERE scope_id LIKE 'private:%'

package/src/memory/migrations/231-repair-memory-graph-event-dates.ts

@@ -12,6 +12,7 @@ interface GraphNodeEventDateRow {
   id: string;
   created: number;
   event_date: number;
+  content: string;
 }
 
 interface EventDateRepair {
@@ -37,9 +38,14 @@ function replaceUtcYear(epochMs: number, year: number): number {
   );
 }
 
+function contentMentionsYear(content: string, year: number): boolean {
+  return new RegExp(`\\b${year}\\b`).test(content);
+}
+
 export function repairMemoryGraphEventDate(
   createdMs: number,
   eventDateMs: number,
+  content: string,
 ): number | null {
   if (!Number.isFinite(createdMs) || !Number.isFinite(eventDateMs)) {
     return null;
@@ -50,6 +56,10 @@ export function repairMemoryGraphEventDate(
   if (createdYear !== REPAIR_CREATED_YEAR) return null;
   if (!CORRUPT_EVENT_YEARS.includes(eventYear as 2024 | 2025)) return null;
 
+  // If the memory's prose explicitly mentions the prior year, the date is
+  // user-anchored history — not the partial-date inference bug — so leave it.
+  if (contentMentionsYear(content, eventYear)) return null;
+
   const corrected = replaceUtcYear(eventDateMs, createdYear);
   if (corrected === eventDateMs) return null;
 
@@ -71,7 +81,7 @@ export function migrate231RepairMemoryGraphEventDates(
     const rows = raw
       .query(
         /*sql*/ `
-          SELECT id, created, event_date
+          SELECT id, created, event_date, content
           FROM memory_graph_nodes
           WHERE event_date IS NOT NULL
             AND CAST(strftime('%Y', created / 1000, 'unixepoch') AS INTEGER) = ?
@@ -85,7 +95,11 @@ export function migrate231RepairMemoryGraphEventDates(
 
     const repairs: EventDateRepair[] = [];
     for (const row of rows) {
-      const corrected = repairMemoryGraphEventDate(row.created, row.event_date);
+      const corrected = repairMemoryGraphEventDate(
+        row.created,
+        row.event_date,
+        row.content ?? "",
+      );
       if (corrected == null) continue;
       repairs.push({
         id: row.id,

package/src/memory/migrations/240-conversation-inference-profile-session.ts

@@ -0,0 +1,25 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+export function migrateConversationInferenceProfileSession(
+  database: DrizzleDb,
+): void {
+  const raw = getSqliteFrom(database);
+  try {
+    raw.exec(
+      `ALTER TABLE conversations ADD COLUMN inference_profile_session_id TEXT DEFAULT NULL`,
+    );
+  } catch {
+    // Column already exists — nothing to do.
+  }
+  try {
+    raw.exec(
+      `ALTER TABLE conversations ADD COLUMN inference_profile_expires_at INTEGER DEFAULT NULL`,
+    );
+  } catch {
+    // Column already exists — nothing to do.
+  }
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_conversations_inference_profile_expires_at ON conversations (inference_profile_expires_at) WHERE inference_profile_expires_at IS NOT NULL`,
+  );
+}

package/src/memory/migrations/241-activation-state-fk-cascade.ts

@@ -0,0 +1,50 @@
+import { type DrizzleDb, getSqliteFrom } from "../db-connection.js";
+
+/**
+ * Rebuild activation_state to add a foreign key on conversation_id with
+ * ON DELETE CASCADE so rows are cleaned up when their conversation is
+ * deleted, matching the pattern of conversation_graph_memory_state and
+ * every other conversation-keyed table. SQLite doesn't support
+ * ALTER TABLE ADD CONSTRAINT, so we rebuild the table; the INSERT...SELECT
+ * filters out any orphan rows already accumulated under the prior schema.
+ */
+export function migrateActivationStateFkCascade(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+  const row = raw
+    .query(
+      `SELECT sql FROM sqlite_master WHERE type='table' AND name='activation_state'`,
+    )
+    .get() as { sql: string } | null;
+  if (!row) return;
+  if (row.sql.includes("ON DELETE CASCADE")) return;
+
+  raw.exec("PRAGMA foreign_keys = OFF");
+  try {
+    raw.exec(/*sql*/ `
+      BEGIN;
+      CREATE TABLE activation_state_new (
+        conversation_id TEXT PRIMARY KEY REFERENCES conversations(id) ON DELETE CASCADE,
+        message_id TEXT NOT NULL,
+        state_json TEXT NOT NULL,
+        ever_injected_json TEXT NOT NULL DEFAULT '[]',
+        current_turn INTEGER NOT NULL DEFAULT 0,
+        updated_at INTEGER NOT NULL
+      );
+      INSERT INTO activation_state_new
+        SELECT a.* FROM activation_state a
+        WHERE EXISTS (SELECT 1 FROM conversations c WHERE c.id = a.conversation_id);
+      DROP TABLE activation_state;
+      ALTER TABLE activation_state_new RENAME TO activation_state;
+      COMMIT;
+    `);
+  } catch (e) {
+    try {
+      raw.exec("ROLLBACK");
+    } catch {
+      /* no active transaction */
+    }
+    throw e;
+  } finally {
+    raw.exec("PRAGMA foreign_keys = ON");
+  }
+}

package/src/memory/migrations/242-message-bookmarks.ts

@@ -0,0 +1,38 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+const CHECKPOINT_KEY = "migration_message_bookmarks_v1";
+
+/**
+ * Create the message_bookmarks table for user-saved message bookmarks.
+ *
+ * Both foreign keys cascade so bookmarks are cleaned up automatically when
+ * their parent message or conversation is deleted. A unique index on
+ * message_id keeps the create-bookmark code path idempotent (a message can
+ * be bookmarked at most once at a time).
+ */
+export function migrateMessageBookmarks(database: DrizzleDb): void {
+  withCrashRecovery(database, CHECKPOINT_KEY, () => {
+    const raw = getSqliteFrom(database);
+
+    raw.exec(/*sql*/ `
+      CREATE TABLE IF NOT EXISTS message_bookmarks (
+        id TEXT PRIMARY KEY,
+        message_id TEXT NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+        conversation_id TEXT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+        created_at INTEGER NOT NULL
+      )
+    `);
+
+    raw.exec(/*sql*/ `
+      CREATE UNIQUE INDEX IF NOT EXISTS message_bookmarks_message_id_uniq
+      ON message_bookmarks (message_id)
+    `);
+
+    raw.exec(/*sql*/ `
+      CREATE INDEX IF NOT EXISTS message_bookmarks_created_at_idx
+      ON message_bookmarks (created_at)
+    `);
+  });
+}

package/src/memory/migrations/243-provider-connections.ts

@@ -0,0 +1,68 @@
+import { type DrizzleDb, getSqliteFrom } from "../db-connection.js";
+
+/**
+ * Creates the `provider_connections` table and seeds the three canonical
+ * connections that every installation ships with.
+ *
+ * Canonical connections:
+ *   - anthropic-managed  → provider=anthropic, auth={type:platform}
+ *   - openai-managed     → provider=openai,    auth={type:platform}
+ *   - gemini-managed     → provider=gemini,    auth={type:platform}
+ *
+ * Idempotent: checks sqlite_master for the table before running DDL;
+ * canonical rows are inserted with INSERT OR IGNORE.
+ */
+export function migrateCreateProviderConnections(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+
+  const tableExists = raw
+    .query(
+      `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'provider_connections'`,
+    )
+    .get();
+
+  if (!tableExists) {
+    try {
+      raw.exec("BEGIN");
+
+      raw.exec(/*sql*/ `
+        CREATE TABLE provider_connections (
+          name        TEXT PRIMARY KEY,
+          provider    TEXT NOT NULL,
+          auth        TEXT NOT NULL,
+          created_at  INTEGER NOT NULL,
+          updated_at  INTEGER NOT NULL
+        )
+      `);
+
+      raw.exec(/*sql*/ `
+        CREATE INDEX idx_provider_connections_provider
+          ON provider_connections(provider)
+      `);
+
+      raw.exec("COMMIT");
+    } catch (e) {
+      try {
+        raw.exec("ROLLBACK");
+      } catch {
+        /* no active transaction */
+      }
+      throw e;
+    }
+  }
+
+  // Seed canonical connections — idempotent via INSERT OR IGNORE.
+  const now = Date.now();
+  const canonicals = [
+    { name: "anthropic-managed", provider: "anthropic", auth: JSON.stringify({ type: "platform" }) },
+    { name: "openai-managed",    provider: "openai",    auth: JSON.stringify({ type: "platform" }) },
+    { name: "gemini-managed",    provider: "gemini",    auth: JSON.stringify({ type: "platform" }) },
+  ];
+
+  for (const { name, provider, auth } of canonicals) {
+    raw.run(
+      `INSERT OR IGNORE INTO provider_connections (name, provider, auth, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`,
+      [name, provider, auth, now, now],
+    );
+  }
+}