@agentstep/agent-sdk 0.1.0

package/src/db/events.ts

@@ -0,0 +1,208 @@
+import { getDb } from "./client";
+import { newId } from "../util/ids";
+import { nowMs, toIso } from "../util/clock";
+import type { EventOrigin, EventRow, ManagedEvent } from "../types";
+
+export interface AppendInput {
+  type: string;
+  payload: Record<string, unknown>;
+  origin: EventOrigin;
+  idempotencyKey?: string | null;
+  processedAt?: number | null;
+}
+
+/**
+ * Append an event to a session's log inside an IMMEDIATE transaction.
+ *
+ * Reserves the next sequence number by reading `sessions.last_seq` and
+ * updating it atomically. Honors the partial-unique idempotency_key index —
+ * if a matching key already exists for this session, the existing row is
+ * returned and no new row is inserted.
+ *
+ * NOTE: this function does NOT emit on the bus. The caller (typically
+ * `lib/sessions/bus.ts`) is responsible for post-commit fan-out, so that
+ * the order "commit first, then emit" is guaranteed.
+ */
+export function appendEvent(sessionId: string, input: AppendInput): EventRow {
+  const db = getDb();
+
+  return db.transaction(() => {
+    if (input.idempotencyKey) {
+      const dupe = db
+        .prepare(
+          `SELECT * FROM events WHERE session_id = ? AND idempotency_key = ?`,
+        )
+        .get(sessionId, input.idempotencyKey) as EventRow | undefined;
+      if (dupe) return dupe;
+    }
+
+    const row = db
+      .prepare(
+        `SELECT last_seq FROM sessions WHERE id = ?`,
+      )
+      .get(sessionId) as { last_seq: number } | undefined;
+    if (!row) throw new Error(`session not found: ${sessionId}`);
+
+    const seq = row.last_seq + 1;
+    const id = newId("evt");
+    const receivedAt = nowMs();
+
+    db.prepare(
+      `INSERT INTO events (
+         id, session_id, seq, type, payload_json,
+         processed_at, received_at, origin, idempotency_key
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      id,
+      sessionId,
+      seq,
+      input.type,
+      JSON.stringify(input.payload),
+      input.processedAt ?? null,
+      receivedAt,
+      input.origin,
+      input.idempotencyKey ?? null,
+    );
+
+    db.prepare(`UPDATE sessions SET last_seq = ?, updated_at = ? WHERE id = ?`).run(
+      seq,
+      receivedAt,
+      sessionId,
+    );
+
+    return {
+      id,
+      session_id: sessionId,
+      seq,
+      type: input.type,
+      payload_json: JSON.stringify(input.payload),
+      processed_at: input.processedAt ?? null,
+      received_at: receivedAt,
+      origin: input.origin,
+      idempotency_key: input.idempotencyKey ?? null,
+    };
+  })();
+}
+
+/**
+ * Append multiple events in a single transaction. Returns the inserted rows
+ * in input order. Same idempotency semantics per row.
+ */
+export function appendEventsBatch(sessionId: string, inputs: AppendInput[]): EventRow[] {
+  const db = getDb();
+
+  return db.transaction(() => {
+    const rows: EventRow[] = [];
+    for (const input of inputs) {
+      if (input.idempotencyKey) {
+        const dupe = db
+          .prepare(
+            `SELECT * FROM events WHERE session_id = ? AND idempotency_key = ?`,
+          )
+          .get(sessionId, input.idempotencyKey) as EventRow | undefined;
+        if (dupe) {
+          rows.push(dupe);
+          continue;
+        }
+      }
+
+      const cur = db
+        .prepare(
+          `SELECT last_seq FROM sessions WHERE id = ?`,
+        )
+        .get(sessionId) as { last_seq: number } | undefined;
+      if (!cur) throw new Error(`session not found: ${sessionId}`);
+
+      const seq = cur.last_seq + 1;
+      const id = newId("evt");
+      const receivedAt = nowMs();
+
+      db.prepare(
+        `INSERT INTO events (
+           id, session_id, seq, type, payload_json,
+           processed_at, received_at, origin, idempotency_key
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      ).run(
+        id,
+        sessionId,
+        seq,
+        input.type,
+        JSON.stringify(input.payload),
+        input.processedAt ?? null,
+        receivedAt,
+        input.origin,
+        input.idempotencyKey ?? null,
+      );
+
+      db.prepare(`UPDATE sessions SET last_seq = ?, updated_at = ? WHERE id = ?`).run(
+        seq,
+        receivedAt,
+        sessionId,
+      );
+
+      rows.push({
+        id,
+        session_id: sessionId,
+        seq,
+        type: input.type,
+        payload_json: JSON.stringify(input.payload),
+        processed_at: input.processedAt ?? null,
+        received_at: receivedAt,
+        origin: input.origin,
+        idempotency_key: input.idempotencyKey ?? null,
+      });
+    }
+    return rows;
+  })();
+}
+
+export function markUserEventProcessed(eventId: string, when: number): void {
+  const db = getDb();
+  db.prepare(`UPDATE events SET processed_at = ? WHERE id = ?`).run(when, eventId);
+}
+
+export function listEvents(
+  sessionId: string,
+  opts: {
+    limit?: number;
+    order?: "asc" | "desc";
+    afterSeq?: number;
+  },
+): EventRow[] {
+  const db = getDb();
+  const limit = Math.min(Math.max(opts.limit ?? 50, 1), 500);
+  const order = opts.order === "desc" ? "DESC" : "ASC";
+  const afterSeq = opts.afterSeq ?? 0;
+
+  return db
+    .prepare(
+      `SELECT * FROM events
+       WHERE session_id = ? AND seq > ?
+       ORDER BY seq ${order}
+       LIMIT ?`,
+    )
+    .all(sessionId, afterSeq, limit) as EventRow[];
+}
+
+export function getLastUnprocessedUserMessage(sessionId: string): EventRow | null {
+  const db = getDb();
+  return (
+    (db
+      .prepare(
+        `SELECT * FROM events WHERE session_id = ? AND type = 'user.message' AND processed_at IS NULL ORDER BY seq DESC LIMIT 1`,
+      )
+      .get(sessionId) as EventRow | undefined) ?? null
+  );
+}
+
+export function rowToManagedEvent(row: EventRow): ManagedEvent {
+  const payload = JSON.parse(row.payload_json) as Record<string, unknown>;
+  return {
+    id: row.id,
+    seq: row.seq,
+    session_id: row.session_id,
+    type: row.type,
+    processed_at: row.processed_at != null ? toIso(row.processed_at) : null,
+    ...payload,
+  };
+}

package/src/db/memory.ts

@@ -0,0 +1,143 @@
+import { createHash } from "node:crypto";
+import { getDb } from "./client";
+import { newId } from "../util/ids";
+import { nowMs, toIso } from "../util/clock";
+import type { MemoryStore, MemoryStoreRow, Memory, MemoryRow } from "../types";
+
+function hydrateStore(row: MemoryStoreRow): MemoryStore {
+  return {
+    id: row.id,
+    name: row.name,
+    description: row.description,
+    created_at: toIso(row.created_at),
+    updated_at: toIso(row.updated_at),
+  };
+}
+
+function hydrateMemory(row: MemoryRow): Memory {
+  return {
+    id: row.id,
+    store_id: row.store_id,
+    path: row.path,
+    content: row.content,
+    content_sha256: row.content_sha256,
+    created_at: toIso(row.created_at),
+    updated_at: toIso(row.updated_at),
+  };
+}
+
+function sha256(content: string): string {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+
+// ── Memory Stores ────────────────────────────────────────────────────────
+
+export function createMemoryStore(input: { name: string; description?: string | null }): MemoryStore {
+  const db = getDb();
+  const id = newId("ms");
+  const now = nowMs();
+  db.prepare(
+    `INSERT INTO memory_stores (id, name, description, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`,
+  ).run(id, input.name, input.description ?? null, now, now);
+  return getMemoryStore(id)!;
+}
+
+export function getMemoryStore(id: string): MemoryStore | null {
+  const db = getDb();
+  const row = db.prepare(`SELECT * FROM memory_stores WHERE id = ?`).get(id) as MemoryStoreRow | undefined;
+  return row ? hydrateStore(row) : null;
+}
+
+export function listMemoryStores(): MemoryStore[] {
+  const db = getDb();
+  const rows = db.prepare(`SELECT * FROM memory_stores ORDER BY created_at DESC`).all() as MemoryStoreRow[];
+  return rows.map(hydrateStore);
+}
+
+export function deleteMemoryStore(id: string): boolean {
+  const db = getDb();
+  const res = db.prepare(`DELETE FROM memory_stores WHERE id = ?`).run(id);
+  return res.changes > 0;
+}
+
+// ── Memories ─────────────────────────────────────────────────────────────
+
+export function createOrUpsertMemory(storeId: string, path: string, content: string): Memory {
+  const db = getDb();
+  const hash = sha256(content);
+  const now = nowMs();
+  const id = newId("mem");
+
+  db.prepare(
+    `INSERT INTO memories (id, store_id, path, content, content_sha256, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(store_id, path) DO UPDATE SET content = excluded.content, content_sha256 = excluded.content_sha256, updated_at = excluded.updated_at`,
+  ).run(id, storeId, path, content, hash, now, now);
+
+  return getMemoryByPath(storeId, path)!;
+}
+
+export function getMemory(id: string): Memory | null {
+  const db = getDb();
+  const row = db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id) as MemoryRow | undefined;
+  return row ? hydrateMemory(row) : null;
+}
+
+export function getMemoryByPath(storeId: string, path: string): Memory | null {
+  const db = getDb();
+  const row = db
+    .prepare(
+      `SELECT * FROM memories WHERE store_id = ? AND path = ?`,
+    )
+    .get(storeId, path) as MemoryRow | undefined;
+  return row ? hydrateMemory(row) : null;
+}
+
+export function listMemories(storeId: string): Memory[] {
+  const db = getDb();
+  const rows = db
+    .prepare(
+      `SELECT * FROM memories WHERE store_id = ? ORDER BY path ASC`,
+    )
+    .all(storeId) as MemoryRow[];
+  return rows.map(hydrateMemory);
+}
+
+export function searchMemories(storeId: string, query: string): Memory[] {
+  const db = getDb();
+  const escaped = query.replace(/%/g, '\\%').replace(/_/g, '\\_');
+  const pattern = `%${escaped}%`;
+  const rows = db
+    .prepare(
+      `SELECT * FROM memories WHERE store_id = ? AND (path LIKE ? ESCAPE '\\' OR content LIKE ? ESCAPE '\\') ORDER BY path ASC`,
+    )
+    .all(storeId, pattern, pattern) as MemoryRow[];
+  return rows.map(hydrateMemory);
+}
+
+export function updateMemory(
+  id: string,
+  content: string,
+  preconditionSha256?: string,
+): { memory: Memory | null; conflict: boolean } {
+  const db = getDb();
+  const existing = getMemory(id);
+  if (!existing) return { memory: null, conflict: false };
+
+  if (preconditionSha256 && existing.content_sha256 !== preconditionSha256) {
+    return { memory: null, conflict: true };
+  }
+
+  const hash = sha256(content);
+  const now = nowMs();
+  db.prepare(
+    `UPDATE memories SET content = ?, content_sha256 = ?, updated_at = ? WHERE id = ?`,
+  ).run(content, hash, now, id);
+  return { memory: getMemory(id), conflict: false };
+}
+
+export function deleteMemory(id: string): boolean {
+  const db = getDb();
+  const res = db.prepare(`DELETE FROM memories WHERE id = ?`).run(id);
+  return res.changes > 0;
+}

package/src/db/migrations.ts

@@ -0,0 +1,295 @@
+import type Database from "libsql";
+
+/**
+ * Idempotent schema. All `CREATE TABLE IF NOT EXISTS`. Safe to re-run on boot.
+ *
+ * Schema locked per plan §Data model. Key decisions:
+ *   - events is append-only with (session_id, seq) unique
+ *   - processed_at is NULLABLE (set on dispatch, not on insert)
+ *   - idempotency_key partial unique index dedupes client retries
+ *   - stats / usage are columnar on sessions (not JSON blobs)
+ *   - environments have async state machine (preparing → ready | failed)
+ *   - sessions.sprite_name is NULL until first user.message (lazy reservation)
+ */
+export function runMigrations(db: InstanceType<typeof Database>): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS api_keys (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      hash TEXT NOT NULL UNIQUE,
+      prefix TEXT NOT NULL,
+      permissions_json TEXT NOT NULL DEFAULT '[]',
+      created_at INTEGER NOT NULL,
+      revoked_at INTEGER
+    );
+
+    CREATE TABLE IF NOT EXISTS settings (
+      key TEXT PRIMARY KEY,
+      value TEXT,
+      type TEXT NOT NULL DEFAULT 'text',
+      updated_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS agents (
+      id TEXT PRIMARY KEY,
+      current_version INTEGER NOT NULL,
+      name TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      archived_at INTEGER
+    );
+
+    CREATE TABLE IF NOT EXISTS agent_versions (
+      agent_id TEXT NOT NULL,
+      version INTEGER NOT NULL,
+      model TEXT NOT NULL,
+      system TEXT,
+      tools_json TEXT NOT NULL DEFAULT '[]',
+      mcp_servers_json TEXT NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL,
+      -- backend column added in migration below (opencode adapter); default
+      -- 'claude' so existing rows and new inserts that omit it work the same
+      PRIMARY KEY (agent_id, version),
+      FOREIGN KEY (agent_id) REFERENCES agents(id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE IF NOT EXISTS environments (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      config_json TEXT NOT NULL,
+      state TEXT NOT NULL DEFAULT 'preparing',
+      state_message TEXT,
+      template_sprite TEXT,
+      checkpoint_id TEXT,
+      created_at INTEGER NOT NULL,
+      archived_at INTEGER
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      agent_id TEXT NOT NULL,
+      agent_version INTEGER NOT NULL,
+      environment_id TEXT NOT NULL,
+      sprite_name TEXT,
+      -- Legacy name: holds any backend's session id (claude's session_id or
+      -- opencode's sessionID). Kept as claude_session_id to avoid schema
+      -- churn; see lib/backends/types.ts for the abstraction.
+      claude_session_id TEXT,
+      status TEXT NOT NULL DEFAULT 'idle',
+      stop_reason TEXT,
+      title TEXT,
+      metadata_json TEXT NOT NULL DEFAULT '{}',
+      turn_count INTEGER NOT NULL DEFAULT 0,
+      tool_calls_count INTEGER NOT NULL DEFAULT 0,
+      active_seconds REAL NOT NULL DEFAULT 0,
+      duration_seconds REAL NOT NULL DEFAULT 0,
+      usage_input_tokens INTEGER NOT NULL DEFAULT 0,
+      usage_output_tokens INTEGER NOT NULL DEFAULT 0,
+      usage_cache_read_input_tokens INTEGER NOT NULL DEFAULT 0,
+      usage_cache_creation_input_tokens INTEGER NOT NULL DEFAULT 0,
+      usage_cost_usd REAL NOT NULL DEFAULT 0,
+      last_seq INTEGER NOT NULL DEFAULT 0,
+      idle_since INTEGER,
+      parked_checkpoint_id TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      archived_at INTEGER,
+      FOREIGN KEY (agent_id, agent_version) REFERENCES agent_versions(agent_id, version),
+      FOREIGN KEY (environment_id) REFERENCES environments(id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_sessions_agent ON sessions(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_sessions_env ON sessions(environment_id);
+    CREATE INDEX IF NOT EXISTS idx_sessions_created_id ON sessions(created_at DESC, id);
+    CREATE INDEX IF NOT EXISTS idx_sessions_status ON sessions(status);
+
+    CREATE TABLE IF NOT EXISTS events (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      seq INTEGER NOT NULL,
+      type TEXT NOT NULL,
+      payload_json TEXT NOT NULL,
+      processed_at INTEGER,
+      received_at INTEGER NOT NULL,
+      origin TEXT NOT NULL,
+      idempotency_key TEXT,
+      FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+    );
+
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_events_session_seq ON events(session_id, seq);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_events_idem
+      ON events(session_id, idempotency_key)
+      WHERE idempotency_key IS NOT NULL;
+
+    -- Proxy routing table: tracks which resource IDs belong to Anthropic's
+    -- hosted MA API. When isProxied(id) returns true, the route handler
+    -- forwards the request to api.anthropic.com instead of handling locally.
+    CREATE TABLE IF NOT EXISTS proxy_resources (
+      resource_id TEXT PRIMARY KEY,
+      resource_type TEXT NOT NULL CHECK(resource_type IN ('agent','environment','session')),
+      created_at INTEGER NOT NULL
+    );
+
+    -- Vault persistence: per-agent key-value stores that persist across sessions.
+    CREATE TABLE IF NOT EXISTS vaults (
+      id TEXT PRIMARY KEY,
+      agent_id TEXT NOT NULL,
+      name TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      FOREIGN KEY (agent_id) REFERENCES agents(id)
+    );
+
+    CREATE TABLE IF NOT EXISTS vault_entries (
+      vault_id TEXT NOT NULL,
+      key TEXT NOT NULL,
+      value TEXT NOT NULL,
+      updated_at INTEGER NOT NULL,
+      PRIMARY KEY (vault_id, key),
+      FOREIGN KEY (vault_id) REFERENCES vaults(id) ON DELETE CASCADE
+    );
+  `);
+
+  // ---------------------------------------------------------------------------
+  // Incremental migrations (add via PRAGMA table_info guards so re-boot is a
+  // no-op on already-migrated DBs). No schema_version table exists yet; when
+  // the migration count grows, introduce one and fold these into it.
+  // ---------------------------------------------------------------------------
+
+  // opencode adapter: backend discriminator on agent_versions
+  const agentVersionCols = db
+    .prepare(`PRAGMA table_info(agent_versions)`)
+    .all() as Array<{ name: string }>;
+  if (!agentVersionCols.some((c) => c.name === "backend")) {
+    db.exec(
+      `ALTER TABLE agent_versions ADD COLUMN backend TEXT NOT NULL DEFAULT 'claude'`,
+    );
+  }
+
+  // Docker provider: provider_name on sessions (defaults to 'sprites' for existing rows)
+  const sessionCols = db
+    .prepare(`PRAGMA table_info(sessions)`)
+    .all() as Array<{ name: string }>;
+  if (!sessionCols.some((c) => c.name === "provider_name")) {
+    db.exec(
+      `ALTER TABLE sessions ADD COLUMN provider_name TEXT NOT NULL DEFAULT 'sprites'`,
+    );
+  }
+
+  // Spec gap 3: max_budget_usd on sessions
+  const sessionCols2 = db
+    .prepare(`PRAGMA table_info(sessions)`)
+    .all() as Array<{ name: string }>;
+  if (!sessionCols2.some((c) => c.name === "max_budget_usd")) {
+    db.exec(`ALTER TABLE sessions ADD COLUMN max_budget_usd REAL`);
+  }
+
+  // Spec gap 4: webhook_url + webhook_events on agent_versions
+  const avCols2 = db
+    .prepare(`PRAGMA table_info(agent_versions)`)
+    .all() as Array<{ name: string }>;
+  if (!avCols2.some((c) => c.name === "webhook_url")) {
+    db.exec(`ALTER TABLE agent_versions ADD COLUMN webhook_url TEXT`);
+  }
+  if (!avCols2.some((c) => c.name === "webhook_events_json")) {
+    db.exec(
+      `ALTER TABLE agent_versions ADD COLUMN webhook_events_json TEXT NOT NULL DEFAULT '["session.status_idle","session.status_running","session.error"]'`,
+    );
+  }
+
+  // Spec gap 6: outcome_criteria_json on sessions
+  const sessionCols3 = db
+    .prepare(`PRAGMA table_info(sessions)`)
+    .all() as Array<{ name: string }>;
+  if (!sessionCols3.some((c) => c.name === "outcome_criteria_json")) {
+    db.exec(`ALTER TABLE sessions ADD COLUMN outcome_criteria_json TEXT`);
+  }
+
+  // Spec gap 7: resources_json on sessions
+  const sessionCols4 = db
+    .prepare(`PRAGMA table_info(sessions)`)
+    .all() as Array<{ name: string }>;
+  if (!sessionCols4.some((c) => c.name === "resources_json")) {
+    db.exec(`ALTER TABLE sessions ADD COLUMN resources_json TEXT`);
+  }
+
+  // Vault persistence: vault_ids_json on sessions
+  const sessionCols5 = db
+    .prepare(`PRAGMA table_info(sessions)`)
+    .all() as Array<{ name: string }>;
+  if (!sessionCols5.some((c) => c.name === "vault_ids_json")) {
+    db.exec(`ALTER TABLE sessions ADD COLUMN vault_ids_json TEXT`);
+  }
+
+  // Multi-agent threads: parent_session_id + thread_depth on sessions
+  const sessionCols6 = db
+    .prepare(`PRAGMA table_info(sessions)`)
+    .all() as Array<{ name: string }>;
+  if (!sessionCols6.some((c) => c.name === "parent_session_id")) {
+    db.exec(`ALTER TABLE sessions ADD COLUMN parent_session_id TEXT`);
+  }
+  if (!sessionCols6.some((c) => c.name === "thread_depth")) {
+    db.exec(
+      `ALTER TABLE sessions ADD COLUMN thread_depth INTEGER NOT NULL DEFAULT 0`,
+    );
+  }
+
+  // Multi-agent threads: threads_enabled on agent_versions
+  const avCols3 = db
+    .prepare(`PRAGMA table_info(agent_versions)`)
+    .all() as Array<{ name: string }>;
+  if (!avCols3.some((c) => c.name === "threads_enabled")) {
+    db.exec(
+      `ALTER TABLE agent_versions ADD COLUMN threads_enabled INTEGER NOT NULL DEFAULT 0`,
+    );
+  }
+
+  // Tool confirmation: confirmation_mode on agent_versions
+  const avCols4 = db
+    .prepare(`PRAGMA table_info(agent_versions)`)
+    .all() as Array<{ name: string }>;
+  if (!avCols4.some((c) => c.name === "confirmation_mode")) {
+    db.exec(
+      `ALTER TABLE agent_versions ADD COLUMN confirmation_mode INTEGER NOT NULL DEFAULT 0`,
+    );
+  }
+
+  // Memory stores
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS memory_stores (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      description TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS memories (
+      id TEXT PRIMARY KEY,
+      store_id TEXT NOT NULL REFERENCES memory_stores(id) ON DELETE CASCADE,
+      path TEXT NOT NULL,
+      content TEXT NOT NULL,
+      content_sha256 TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      UNIQUE(store_id, path)
+    )
+  `);
+
+  // Index on parent_session_id for thread listing
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_sessions_parent
+      ON sessions(parent_session_id) WHERE parent_session_id IS NOT NULL
+  `);
+
+  // callable_agents on agent_versions (for multi-agent thread config)
+  const avCols5 = db
+    .prepare(`PRAGMA table_info(agent_versions)`)
+    .all() as Array<{ name: string }>;
+  if (!avCols5.some((c) => c.name === "callable_agents_json")) {
+    db.exec(
+      `ALTER TABLE agent_versions ADD COLUMN callable_agents_json TEXT`,
+    );
+  }
+}

package/src/db/proxy.ts

@@ -0,0 +1,37 @@
+/**
+ * Proxy routing table: tracks which resource IDs belong to Anthropic's
+ * hosted Managed Agents API. The route handlers check `isProxied(id)`
+ * before touching local state — if true, they forward to Anthropic.
+ *
+ * Anthropic owns the IDs (they're assigned by their API on create). We
+ * store them in this table after a successful proxy-create so subsequent
+ * requests for that ID auto-route without the client needing to specify
+ * anything.
+ */
+import { getDb } from "./client";
+import { nowMs } from "../util/clock";
+
+export type ProxiedResourceType = "agent" | "environment" | "session";
+
+export function isProxied(id: string): boolean {
+  const db = getDb();
+  const row = db
+    .prepare(
+      `SELECT resource_id FROM proxy_resources WHERE resource_id = ?`,
+    )
+    .get(id) as { resource_id: string } | undefined;
+  return !!row;
+}
+
+export function markProxied(id: string, type: ProxiedResourceType): void {
+  const db = getDb();
+  db.prepare(
+    `INSERT OR IGNORE INTO proxy_resources (resource_id, resource_type, created_at)
+     VALUES (?, ?, ?)`,
+  ).run(id, type, nowMs());
+}
+
+export function unmarkProxied(id: string): void {
+  const db = getDb();
+  db.prepare(`DELETE FROM proxy_resources WHERE resource_id = ?`).run(id);
+}