@hheei/pi-subagents 0.2.4 → 0.4.0

package/dist/runtime.js

@@ -7,13 +7,14 @@
  * registry only records which runtime and endpoint a child was last launched with.
  */
 import { randomBytes, randomUUID } from "node:crypto";
-import { mkdirSync, readFileSync } from "node:fs";
-import { chmod, mkdir, rename, writeFile } from "node:fs/promises";
+import { chmod, mkdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { errorMessage } from "@hheei/pi-ext-core";
 import { spawnChildRuntime } from "./child-process.js";
 import { buildLaunchSpec, withBridgeToken } from "./launch-spec.js";
+import { commitLease } from "./lease.js";
+import { defaultStatePath, deleteToken, openStateDb, readToken, writeToken } from "./state-db.js";
 function runtimeDirectory() {
     const user = typeof process.getuid === "function" ? process.getuid() : "user";
     return join(tmpdir(), `pi-subagents-${user}`);
@@ -22,82 +23,46 @@ function runtimeDirectory() {
  * The one socket a parent session listens on. A child dials this path, so a parent that restarts
  * re-listens in the same place and a surviving child reconnects instead of being rebuilt.
  */
-export function parentBridgeEndpoint(parentSessionId) {
-    return join(runtimeDirectory(), `parent-${parentSessionId}.sock`);
+export function parentBridgeEndpoint(_parentSessionId) {
+    return defaultStatePath();
 }
-/**
- * Every parent session keeps its own token file. One shared file is rewritten wholesale by whichever
- * parent saved last, so two parent sessions in the same runtime directory would erase each other's
- * credentials and a child that survived a restart could no longer authorize itself.
- */
-export function parentTokenFile(parentSessionId) {
-    return join(runtimeDirectory(), `tokens-${parentSessionId}.json`);
+/** Tokens live in the same sqlite file as the child ledger. Rows do not clobber each other. */
+export function parentTokenFile(_parentSessionId) {
+    return defaultStatePath();
 }
 /**
- * Tokens outlive the parent process: a child that survived (a panel child, or one whose parent was
- * killed) reconnects with the token it was launched with, and a restarted parent must be able to
- * authorize it without holding the old process's memory. The store is a 0600 file in the 0700
- * runtime directory; the registry never sees a token.
+ * Tokens outlive the parent process. A restarted parent reads the same sqlite file and can still
+ * match the token a surviving child was launched with.
  */
 export function createRuntimeTokenStore(options) {
-    const file = options.file ?? parentTokenFile(options.parentSessionId);
+    const file = options.file ?? defaultStatePath();
     const diagnose = options.diagnose ?? (() => { });
-    const tokens = new Map(readStoredTokens(file, diagnose));
-    let writing = Promise.resolve();
-    const persist = () => {
-        const payload = `${JSON.stringify(Object.fromEntries(tokens))}\n`;
-        writing = writing
-            .then(async () => {
-            mkdirSync(runtimeDirectory(), { recursive: true, mode: 0o700 });
-            // Writing in place truncates the file first, and a parent killed inside that window would
-            // leave every surviving child locked out of the bridge. The swap is atomic instead.
-            const temporary = `${file}.${process.pid}.tmp`;
-            await writeFile(temporary, payload, { mode: 0o600 });
-            await rename(temporary, file);
-        })
-            .catch((error) => {
-            diagnose(`could not persist bridge tokens: ${errorMessage(error)}`);
-        });
-    };
+    let db;
+    try {
+        db = openStateDb(file);
+    }
+    catch (error) {
+        diagnose(`could not open the state database: ${errorMessage(error)}`);
+    }
+    const database = db;
     return {
         remember(runtimeIdentity, token) {
-            tokens.set(runtimeIdentity, token);
-            persist();
+            if (database === undefined)
+                return;
+            writeToken(database, options.parentSessionId, runtimeIdentity, token);
         },
         get(runtimeIdentity) {
-            return tokens.get(runtimeIdentity);
+            if (database === undefined)
+                return undefined;
+            return readToken(database, options.parentSessionId, runtimeIdentity);
         },
         forget(runtimeIdentity) {
-            if (tokens.delete(runtimeIdentity))
-                persist();
+            if (database === undefined)
+                return;
+            deleteToken(database, options.parentSessionId, runtimeIdentity);
         },
     };
 }
-function readStoredTokens(file, diagnose) {
-    let raw;
-    try {
-        raw = readFileSync(file, "utf8");
-    }
-    catch (error) {
-        const code = error.code;
-        if (code !== "ENOENT")
-            diagnose(`could not read bridge tokens: ${errorMessage(error)}`);
-        return [];
-    }
-    if (raw.trim() === "")
-        return [];
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        diagnose(`bridge token file is not valid JSON: ${errorMessage(error)}`);
-        return [];
-    }
-    if (typeof parsed !== "object" || parsed === null)
-        return [];
-    return Object.entries(parsed).filter((entry) => typeof entry[1] === "string");
-}
 /**
  * Mints the runtime identity and its bridge token, remembers the token so the child's very first
  * hello can be authorized, and builds the one LaunchSpec for this presentation. The token travels
@@ -125,10 +90,11 @@ function planChildRuntime(record, tokens, presentation) {
 }
 /** Evidence first: the record names the runtime that was asked for even if starting it fails. */
 async function recordRuntimeEvidence(registry, record, plan) {
-    await registry.update(record.subagentId, undefined, (current) => ({
-        ...current,
-        runtime: { runtimeIdentity: plan.runtimeIdentity, endpoint: plan.endpoint },
-    }));
+    await commitLease(registry, record.subagentId, {
+        type: "runtime-bound",
+        runtimeIdentity: plan.runtimeIdentity,
+        endpoint: plan.endpoint,
+    });
 }
 /**
  * Starts one headless child Pi and waits for it to connect. Nothing is driven over its stdio: the
@@ -155,22 +121,22 @@ export async function launchChild(options) {
         options.diagnose?.(`bridge wait failed: ${errorMessage(error)}`);
         connected = false;
     }
-    if (connected)
+    if (connected) {
+        await bindProcess(options.registry, record.subagentId, runtime.pid);
         return { handle: runtime };
+    }
     await runtime.terminate();
     if (runtime.alive) {
         // The process outlived termination, so it is not gone and the caller keeps the handle: it is
         // the only thing that can try again.
+        await bindProcess(options.registry, record.subagentId, runtime.pid);
         return {
             handle: runtime,
             failure: `Child ${record.subagentId} never connected to the parent bridge and did not stop (it may still be running)`,
         };
     }
     options.tokens.forget(plan.runtimeIdentity);
-    await options.registry.update(record.subagentId, undefined, (current) => {
-        const { runtime: _runtime, ...rest } = current;
-        return rest;
-    }, plan.runtimeIdentity);
+    await commitLease(options.registry, record.subagentId, { type: "runtime-gone", outcome: "clear" }, undefined, plan.runtimeIdentity);
     return { failure: `Child ${record.subagentId} never connected to the parent bridge` };
 }
 /**
@@ -191,8 +157,7 @@ export async function openChildPanel(options) {
         // failing to report it. The token is kept so a child that does come up can still be adopted,
         // and the caller is told the runtime is unconfirmed instead of that nothing was started.
         return {
-            unconfirmed: true,
-            failure: `Child ${record.subagentId} could not be opened in a ${options.host.kind} panel (${errorMessage(error)}); a panel may have been created, so stop the child before sending again`,
+            failure: `Child ${record.subagentId} could not be opened in a ${options.host.kind} panel (${errorMessage(error)}); a panel may have been created, so close it if it is still there`,
         };
     }
     let connected;
@@ -203,25 +168,24 @@ export async function openChildPanel(options) {
         options.diagnose?.(`bridge wait failed: ${errorMessage(error)}`);
         connected = false;
     }
-    if (connected)
+    if (connected) {
+        await bindPanel(options.registry, record.subagentId, options.host.kind, attachment.identity.attachmentId);
         return { handle: attachment };
-    // The child never dialed in, so the panel is closed again — and only a host that confirms it is
-    // gone counts. While it may still run, the caller keeps the handle and the token: the handle is
-    // what stops a second runtime from being started for the same session, and the token is what lets
-    // a child that does come up be adopted instead of lingering as a process nobody owns.
+    }
+    // The child never dialed in, so the panel is closed again. A host that cannot confirm it is gone
+    // keeps the handle, so stop can try the close again, and the token, so a child that does come up
+    // can still be adopted. The handle does not block a later send.
     const cleanup = await attachment.cleanup();
     const observed = await attachment.observe();
     if (!(observed.known && !observed.alive)) {
+        await bindPanel(options.registry, record.subagentId, options.host.kind, attachment.identity.attachmentId);
         return {
             handle: attachment,
             failure: `Child ${record.subagentId} never connected to the parent bridge and its panel could not be closed (${cleanup.stderr || "its state could not be observed"}); close it manually`,
         };
     }
     options.tokens.forget(plan.runtimeIdentity);
-    await options.registry.update(record.subagentId, undefined, (current) => {
-        const { runtime: _runtime, ...rest } = current;
-        return rest;
-    }, plan.runtimeIdentity);
+    await commitLease(options.registry, record.subagentId, { type: "runtime-gone", outcome: "clear" }, undefined, plan.runtimeIdentity);
     return { failure: `Child ${record.subagentId} never connected to the parent bridge` };
 }
 /** Creates the runtime directory if needed; the socket itself is 0600 in a 0700 directory. */
@@ -233,3 +197,17 @@ export async function prepareRuntimeDirectory(diagnose) {
     });
     return directory;
 }
+async function bindProcess(registry, id, pid) {
+    if (pid === undefined)
+        return;
+    await commitLease(registry, id, {
+        type: "attachment-bound",
+        attachment: { kind: "process", pid },
+    });
+}
+async function bindPanel(registry, id, host, attachmentId) {
+    await commitLease(registry, id, {
+        type: "attachment-bound",
+        attachment: { kind: "panel", host, id: attachmentId },
+    });
+}

package/dist/session-bootstrap.d.ts

@@ -1,6 +1,8 @@
 import type { ModelRegistryLike, ParentAgentDefaults, SkillCatalogEntry } from "./agent-resolver.js";
 import type { EffectiveLaunchConfig, PersistenceState, PiInvocation, Presentation, SpawnSubagentInput, SubagentRecord } from "./domain.js";
 import type { SubagentRegistry } from "./registry.js";
+/** Reads all JSON entries from a session file on disk. */
+export declare function readSessionJsonlEntries(sessionPath: string): Promise<unknown[]>;
 export interface SessionPlacement {
     readonly sessionId: string;
     readonly sessionDir: string;
@@ -62,7 +64,6 @@ export interface ResolveSubagentLaunchOptions {
     readonly existingSubagentIds?: readonly string[];
     readonly enforceEnabled?: boolean;
     readonly sessionPath?: string;
-    readonly referencedSessionPath?: string;
 }
 /**
  * One resolution chain for a spawn: agent definition + explicit parent defaults

package/dist/session-bootstrap.js

@@ -1,13 +1,27 @@
 import { randomUUID } from "node:crypto";
-import { open, readdir, stat } from "node:fs/promises";
+import { open, readdir, readFile, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, SessionManager } from "@earendil-works/pi-coding-agent";
 import { isRecord } from "@hheei/pi-ext-core";
 import { resolveAgent } from "./agent-resolver.js";
 import { builtinAgentToolProblem } from "./builtin-agents.js";
 import { isSessionId } from "./domain.js";
 import { assembleChildPrompt, resolveBridgeExtensionPath, resolvePiInvocation, } from "./launch-spec.js";
-import { formatSessionReferencePrompt } from "./session-fork.js";
+/** Reads all JSON entries from a session file on disk. */
+export async function readSessionJsonlEntries(sessionPath) {
+    const raw = await readFile(sessionPath, "utf8");
+    const lines = raw.split("\n").filter((line) => line.trim() !== "");
+    const entries = [];
+    for (const line of lines) {
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            // ignore trailing malformed line
+        }
+    }
+    return entries;
+}
 /** Bounded read for a session header; the first line holds the whole identity of the file. */
 const HEADER_READ_BYTES = 64 * 1024;
 /**
@@ -151,10 +165,10 @@ export function createSubagentId(existingIds) {
 export async function resolveSubagentLaunch(options) {
     const task = options.input.task.trim();
     if (task === "")
-        throw new Error("spawn_agent requires a non-empty task");
+        throw new Error("agent_spawn requires a non-empty task");
     const name = options.input.agent?.trim();
     if (name === undefined || name === "") {
-        throw new Error("spawn_agent requires an explicit agent name; V1 has no built-in default agent");
+        throw new Error("agent_spawn requires an explicit agent name; V1 has no built-in default agent");
     }
     const cwd = resolve(options.input.cwd?.trim() || options.cwd);
     const requestedTitle = options.input.title?.trim();
@@ -174,12 +188,9 @@ export async function resolveSubagentLaunch(options) {
         ...(options.onWarning === undefined ? {} : { onWarning: options.onWarning }),
     });
     if (options.enforceEnabled === true && policy.enabled === false) {
-        throw new Error(`Agent "${policy.agent.name}" is disabled: no model is specified in user configuration (~/.pi/agent/agents/ or .pi/agents/)`);
-    }
-    let instructions = policy.agent.instructions;
-    if (options.referencedSessionPath !== undefined && options.referencedSessionPath.trim() !== "") {
-        instructions = `${instructions.trim()}\n\n${formatSessionReferencePrompt(options.referencedSessionPath)}`;
+        throw new Error(`Agent "${policy.agent.name}" is disabled: no model is specified in user configuration (${join(getAgentDir(), "agents")}/ or .pi/agents/)`);
     }
+    const instructions = policy.agent.instructions;
     return Object.freeze({
         subagentId,
         invocation: options.invocation ?? resolvePiInvocation(),
@@ -187,9 +198,6 @@ export async function resolveSubagentLaunch(options) {
         sessionId,
         sessionDir: resolveSubagentSessionDir(cwd),
         ...(options.sessionPath === undefined ? {} : { sessionPath: options.sessionPath }),
-        ...(options.referencedSessionPath === undefined
-            ? {}
-            : { referencedSessionPath: options.referencedSessionPath }),
         agent: policy.agent,
         model: policy.model,
         thinking: policy.thinking,
@@ -197,9 +205,9 @@ export async function resolveSubagentLaunch(options) {
         excludeTools: policy.excludeTools,
         extensions: policy.extensions,
         skills: policy.skills,
+        mcp: policy.mcp,
         prompt: assembleChildPrompt(instructions),
         bridgeExtensionPath,
-        interactive: policy.interactive,
         ...(policy.codemodeOnly ? { codemodeOnly: true } : {}),
         ...(title === undefined ? {} : { title }),
     });

package/dist/state-db.d.ts

@@ -0,0 +1,52 @@
+import { DatabaseSync } from "node:sqlite";
+/** The one durable file for child records, commands, and tokens. */
+export declare function defaultStatePath(): string;
+export declare function openStateDb(filePath: string): DatabaseSync;
+export declare function withWrite<T>(db: DatabaseSync, run: () => T): T;
+export interface StoredCommand {
+    readonly id: string;
+    readonly parentSessionId: string;
+    readonly subagentId: string;
+    readonly direction: "to_child" | "to_parent";
+    readonly operation: string;
+    readonly payload: string;
+    readonly status: string;
+    readonly result: string | null;
+    readonly errorCode: string | null;
+    readonly error: string | null;
+}
+export declare function insertChild(db: DatabaseSync, parentSessionId: string, subagentId: string, revision: number, record: string): boolean;
+export declare function readChild(db: DatabaseSync, parentSessionId: string, subagentId: string): {
+    readonly revision: number;
+    readonly record: string;
+} | undefined;
+export declare function listChildRecords(db: DatabaseSync, parentSessionId: string): readonly string[];
+export declare function replaceChild(db: DatabaseSync, parentSessionId: string, subagentId: string, expectedRevision: number | undefined, revision: number, record: string): boolean;
+export declare function readMeta(db: DatabaseSync, parentSessionId: string, key: string): string | undefined;
+export declare function writeMeta(db: DatabaseSync, parentSessionId: string, key: string, value: string): void;
+export declare function enqueueCommand(db: DatabaseSync, command: {
+    readonly id: string;
+    readonly parentSessionId: string;
+    readonly subagentId: string;
+    readonly direction: "to_child" | "to_parent";
+    readonly operation: string;
+    readonly payload: string;
+    readonly createdAt: number;
+}): void;
+export declare function hasPendingCommand(db: DatabaseSync, parentSessionId: string, direction: "to_child" | "to_parent", subagentId?: string): boolean;
+export declare function claimCommand(db: DatabaseSync, parentSessionId: string, subagentId: string, direction: "to_child" | "to_parent"): StoredCommand | undefined;
+export declare function claimParentCommands(db: DatabaseSync, parentSessionId: string): readonly StoredCommand[];
+export declare function requeueAbandonedParentCommands(db: DatabaseSync, parentSessionId: string): void;
+export declare function deleteCommand(db: DatabaseSync, id: string): void;
+export declare function readCommand(db: DatabaseSync, id: string): StoredCommand | undefined;
+export declare function finishCommand(db: DatabaseSync, id: string, outcome: {
+    readonly status: "done";
+    readonly result: string;
+} | {
+    readonly status: "failed";
+    readonly errorCode: string;
+    readonly error: string;
+}): void;
+export declare function readToken(db: DatabaseSync, parentSessionId: string, runtimeIdentity: string): string | undefined;
+export declare function writeToken(db: DatabaseSync, parentSessionId: string, runtimeIdentity: string, token: string): void;
+export declare function deleteToken(db: DatabaseSync, parentSessionId: string, runtimeIdentity: string): void;

package/dist/state-db.js

@@ -0,0 +1,209 @@
+import { chmodSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+/** The one durable file for child records, commands, and tokens. */
+export function defaultStatePath() {
+    return join(getAgentDir(), "pi-subagents", "state.sqlite");
+}
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS children (
+  parent_session_id TEXT NOT NULL,
+  subagent_id TEXT NOT NULL,
+  revision INTEGER NOT NULL,
+  record TEXT NOT NULL,
+  PRIMARY KEY (parent_session_id, subagent_id)
+);
+CREATE TABLE IF NOT EXISTS session_meta (
+  parent_session_id TEXT NOT NULL,
+  key TEXT NOT NULL,
+  value TEXT NOT NULL,
+  PRIMARY KEY (parent_session_id, key)
+);
+CREATE TABLE IF NOT EXISTS commands (
+  id TEXT PRIMARY KEY,
+  parent_session_id TEXT NOT NULL,
+  subagent_id TEXT NOT NULL,
+  direction TEXT NOT NULL,
+  operation TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  status TEXT NOT NULL,
+  result TEXT,
+  error_code TEXT,
+  error TEXT,
+  created_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS commands_pending
+  ON commands (parent_session_id, subagent_id, direction, status, created_at);
+CREATE TABLE IF NOT EXISTS tokens (
+  parent_session_id TEXT NOT NULL,
+  runtime_identity TEXT NOT NULL,
+  token TEXT NOT NULL,
+  PRIMARY KEY (parent_session_id, runtime_identity)
+);
+`;
+const connections = new Map();
+export function openStateDb(filePath) {
+    const cached = connections.get(filePath);
+    if (cached !== undefined)
+        return cached;
+    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    const db = new DatabaseSync(filePath);
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec(SCHEMA);
+    db.exec("DROP TABLE IF EXISTS presence");
+    chmodSync(filePath, 0o600);
+    connections.set(filePath, db);
+    return db;
+}
+export function withWrite(db, run) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const value = run();
+        db.exec("COMMIT");
+        return value;
+    }
+    catch (error) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            // The original error is the one the caller handles.
+        }
+        throw error;
+    }
+}
+function commandFromRow(row) {
+    return {
+        id: row.id,
+        parentSessionId: row.parent_session_id,
+        subagentId: row.subagent_id,
+        direction: row.direction === "to_parent" ? "to_parent" : "to_child",
+        operation: row.operation,
+        payload: row.payload,
+        status: row.status,
+        result: row.result,
+        errorCode: row.error_code,
+        error: row.error,
+    };
+}
+const COMMAND_COLUMNS = "id, parent_session_id, subagent_id, direction, operation, payload, status, result, error_code, error";
+export function insertChild(db, parentSessionId, subagentId, revision, record) {
+    const result = db
+        .prepare(`INSERT INTO children (parent_session_id, subagent_id, revision, record)
+			 VALUES (?, ?, ?, ?)
+			 ON CONFLICT DO NOTHING`)
+        .run(parentSessionId, subagentId, revision, record);
+    return Number(result.changes) === 1;
+}
+export function readChild(db, parentSessionId, subagentId) {
+    const row = db
+        .prepare("SELECT revision, record FROM children WHERE parent_session_id = ? AND subagent_id = ?")
+        .get(parentSessionId, subagentId);
+    return row;
+}
+export function listChildRecords(db, parentSessionId) {
+    const rows = db
+        .prepare("SELECT record FROM children WHERE parent_session_id = ? ORDER BY record")
+        .all(parentSessionId);
+    return rows.map((row) => row.record);
+}
+export function replaceChild(db, parentSessionId, subagentId, expectedRevision, revision, record) {
+    const result = expectedRevision === undefined
+        ? db
+            .prepare(`UPDATE children SET revision = ?, record = ?
+						 WHERE parent_session_id = ? AND subagent_id = ?`)
+            .run(revision, record, parentSessionId, subagentId)
+        : db
+            .prepare(`UPDATE children SET revision = ?, record = ?
+						 WHERE parent_session_id = ? AND subagent_id = ? AND revision = ?`)
+            .run(revision, record, parentSessionId, subagentId, expectedRevision);
+    return Number(result.changes) === 1;
+}
+export function readMeta(db, parentSessionId, key) {
+    const row = db
+        .prepare("SELECT value FROM session_meta WHERE parent_session_id = ? AND key = ?")
+        .get(parentSessionId, key);
+    return row?.value;
+}
+export function writeMeta(db, parentSessionId, key, value) {
+    db.prepare(`INSERT INTO session_meta (parent_session_id, key, value) VALUES (?, ?, ?)
+		 ON CONFLICT (parent_session_id, key) DO UPDATE SET value = excluded.value`).run(parentSessionId, key, value);
+}
+export function enqueueCommand(db, command) {
+    db.prepare(`INSERT INTO commands (
+		   id, parent_session_id, subagent_id, direction, operation, payload, status, created_at
+		 ) VALUES (?, ?, ?, ?, ?, ?, 'pending', ?)`).run(command.id, command.parentSessionId, command.subagentId, command.direction, command.operation, command.payload, command.createdAt);
+}
+export function hasPendingCommand(db, parentSessionId, direction, subagentId) {
+    const row = subagentId === undefined
+        ? db
+            .prepare(`SELECT 1 AS hit FROM commands
+						 WHERE parent_session_id = ? AND direction = ? AND status = 'pending'
+						 LIMIT 1`)
+            .get(parentSessionId, direction)
+        : db
+            .prepare(`SELECT 1 AS hit FROM commands
+						 WHERE parent_session_id = ? AND subagent_id = ? AND direction = ? AND status = 'pending'
+						 LIMIT 1`)
+            .get(parentSessionId, subagentId, direction);
+    return row !== undefined;
+}
+export function claimCommand(db, parentSessionId, subagentId, direction) {
+    const row = db
+        .prepare(`UPDATE commands SET status = 'working'
+			 WHERE id = (
+			   SELECT id FROM commands
+			   WHERE parent_session_id = ? AND subagent_id = ? AND direction = ? AND status = 'pending'
+			   ORDER BY created_at
+			   LIMIT 1
+			 )
+			 RETURNING ${COMMAND_COLUMNS}`)
+        .get(parentSessionId, subagentId, direction);
+    return row === undefined ? undefined : commandFromRow(row);
+}
+export function claimParentCommands(db, parentSessionId) {
+    const rows = db
+        .prepare(`UPDATE commands SET status = 'working'
+			 WHERE id IN (
+			   SELECT id FROM commands
+			   WHERE parent_session_id = ? AND direction = 'to_parent' AND status = 'pending'
+			   ORDER BY created_at
+			   LIMIT 20
+			 )
+			 RETURNING ${COMMAND_COLUMNS}`)
+        .all(parentSessionId);
+    return rows.map(commandFromRow);
+}
+export function requeueAbandonedParentCommands(db, parentSessionId) {
+    db.prepare(`UPDATE commands SET status = 'pending'
+		 WHERE parent_session_id = ? AND direction = 'to_parent' AND status = 'working'`).run(parentSessionId);
+}
+export function deleteCommand(db, id) {
+    db.prepare("DELETE FROM commands WHERE id = ?").run(id);
+}
+export function readCommand(db, id) {
+    const row = db.prepare(`SELECT ${COMMAND_COLUMNS} FROM commands WHERE id = ?`).get(id);
+    return row === undefined ? undefined : commandFromRow(row);
+}
+export function finishCommand(db, id, outcome) {
+    if (outcome.status === "done") {
+        db.prepare("UPDATE commands SET status = 'done', result = ? WHERE id = ?").run(outcome.result, id);
+        return;
+    }
+    db.prepare("UPDATE commands SET status = 'failed', error_code = ?, error = ? WHERE id = ?").run(outcome.errorCode, outcome.error, id);
+}
+export function readToken(db, parentSessionId, runtimeIdentity) {
+    const row = db
+        .prepare("SELECT token FROM tokens WHERE parent_session_id = ? AND runtime_identity = ?")
+        .get(parentSessionId, runtimeIdentity);
+    return row?.token;
+}
+export function writeToken(db, parentSessionId, runtimeIdentity, token) {
+    db.prepare(`INSERT INTO tokens (parent_session_id, runtime_identity, token) VALUES (?, ?, ?)
+		 ON CONFLICT (parent_session_id, runtime_identity) DO UPDATE SET token = excluded.token`).run(parentSessionId, runtimeIdentity, token);
+}
+export function deleteToken(db, parentSessionId, runtimeIdentity) {
+    db.prepare("DELETE FROM tokens WHERE parent_session_id = ? AND runtime_identity = ?").run(parentSessionId, runtimeIdentity);
+}

package/dist/state.d.ts

@@ -6,9 +6,17 @@ export interface StateSnapshot {
     readonly activeTool?: string;
     readonly usage: UsageSummary;
 }
+export interface TranscriptFacts {
+    readonly usage: UsageSummary;
+    readonly summary?: string;
+    readonly stopReason?: string;
+    readonly interrupted?: string;
+    readonly containsInput: boolean;
+}
 export interface StateProjector {
     applyEvent(event: unknown): StateSnapshot;
     rebuild(entries: readonly unknown[]): StateSnapshot;
+    applyTranscriptFacts(facts: TranscriptFacts): StateSnapshot;
     /**
      * Puts the projected state back in step with a state the child itself reported. Without it a
      * transcript that still ends in a tool result keeps projecting "running" over a child that has
@@ -19,4 +27,21 @@ export interface StateProjector {
 }
 export declare function summarizeCurrentBranch(entries: readonly unknown[]): string | undefined;
 export declare function aggregateUsage(entries: readonly unknown[]): UsageSummary;
+/** What the parent projects from a session. The transcript itself never crosses the bridge. */
+export declare function transcriptFacts(entries: readonly unknown[], expectedInput?: string): TranscriptFacts;
+/** A mailbox answer is untrusted. Anything that is not these fields is not facts. */
+export declare function parseTranscriptFacts(value: unknown): TranscriptFacts | undefined;
+/** The phase a streaming assistant update is in: what the parent shows as the child's activity. */
+export type AssistantPhaseKind = "thinking" | "generating" | "toolcall";
+export interface AssistantPhase {
+    readonly kind: AssistantPhaseKind;
+    /** The tool being streamed, when the phase is a tool call. */
+    readonly toolName?: string;
+}
+/**
+ * Categorizes a streaming assistant update into the phase the parent projects. The child throttles
+ * duplicate deltas with the same answer, so both ends of the bridge agree on what "still thinking"
+ * means instead of each re-deriving it from a different subset of the event.
+ */
+export declare function assistantUpdatePhase(assistantMessageEvent: unknown, message: unknown): AssistantPhase | undefined;
 export declare function createStateProjector(initialState?: SubagentState): StateProjector;