@hheei/pi-subagents 0.7.0 → 0.8.0

package/dist/state-db.js

@@ -2,11 +2,17 @@ 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. */
+/** The one durable file for child records, the mailbox, and delegation receipts. */
 export function defaultStatePath() {
     return join(getAgentDir(), "pi-subagents", "state.sqlite");
 }
-const SCHEMA = `
+/**
+ * Bumped only when an existing ledger needs work. A ledger written by a newer version is refused
+ * instead of being rewritten: this file is runtime state, but silently discarding another build's
+ * records is worse than failing to start.
+ */
+const SCHEMA_VERSION = 2;
+const TABLES = `
 CREATE TABLE IF NOT EXISTS children (
   parent_session_id TEXT NOT NULL,
   subagent_id TEXT NOT NULL,
@@ -33,27 +39,91 @@ CREATE TABLE IF NOT EXISTS commands (
   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 (
+CREATE TABLE IF NOT EXISTS delegations (
   parent_session_id TEXT NOT NULL,
-  runtime_identity TEXT NOT NULL,
-  token TEXT NOT NULL,
-  PRIMARY KEY (parent_session_id, runtime_identity)
+  delegation_id TEXT NOT NULL,
+  child_id TEXT,
+  delegation_revision INTEGER,
+  task TEXT NOT NULL,
+  input_checkpoint TEXT,
+  run_boundary INTEGER,
+  control_id TEXT,
+  status TEXT NOT NULL,
+  delivery TEXT NOT NULL,
+  result_text TEXT,
+  safe_to_retry INTEGER,
+  side_effects TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (parent_session_id, delegation_id)
 );
 `;
+/**
+ * Indexes are created after the column repair below, because a ledger that predates
+ * `delegation_revision` cannot index it yet.
+ */
+const INDEXES = `
+CREATE INDEX IF NOT EXISTS commands_pending
+  ON commands (parent_session_id, subagent_id, direction, status, created_at);
+CREATE INDEX IF NOT EXISTS delegations_child
+  ON delegations (parent_session_id, child_id, status);
+CREATE UNIQUE INDEX IF NOT EXISTS delegations_revision
+  ON delegations (parent_session_id, child_id, delegation_revision);
+`;
+/**
+ * Columns added to a table that already exists. `CREATE TABLE IF NOT EXISTS` leaves an older
+ * table untouched, so an 11-column `delegations` would keep failing the indexes above.
+ */
+const ADDED_COLUMNS = [
+    ["delegations", "delegation_revision", "INTEGER"],
+    ["delegations", "control_id", "TEXT"],
+    ["delegations", "safe_to_retry", "INTEGER"],
+    ["delegations", "side_effects", "TEXT"],
+];
 const connections = new Map();
+function schemaVersion(db) {
+    return Number(db.prepare("PRAGMA user_version").get()?.user_version ?? 0);
+}
+/** Brings any older ledger to {@link SCHEMA_VERSION} in place, keeping every row. */
+function migrate(db) {
+    const version = schemaVersion(db);
+    if (version > SCHEMA_VERSION) {
+        throw new Error(`the subagent ledger was written by a newer version (schema ${version}); this version understands schema ${SCHEMA_VERSION}`);
+    }
+    if (version === SCHEMA_VERSION)
+        return;
+    withWrite(db, () => {
+        if (schemaVersion(db) === SCHEMA_VERSION)
+            return;
+        db.exec(TABLES);
+        for (const [table, column, type] of ADDED_COLUMNS) {
+            const columns = db.prepare(`PRAGMA table_info(${table})`).all();
+            if (columns.some((existing) => existing.name === column))
+                continue;
+            db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+        }
+        // The bridge token had no reader once the mailbox replaced the socket handshake.
+        db.exec("DROP TABLE IF EXISTS tokens");
+        db.exec(INDEXES);
+        db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+    });
+}
 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);
+    try {
+        db.exec("PRAGMA busy_timeout = 5000");
+        db.exec("PRAGMA journal_mode = WAL");
+        migrate(db);
+        chmodSync(filePath, 0o600);
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
     connections.set(filePath, db);
     return db;
 }
@@ -194,16 +264,24 @@ export function finishCommand(db, id, outcome) {
     }
     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);
+/**
+ * A settled command whose waiter died with its process has no reader left. Only a parent that is
+ * taking over the mailbox may run this: a live waiter deletes its own row when it reads it.
+ */
+export function deleteSettledCommands(db, parentSessionId) {
+    db.prepare(`DELETE FROM commands
+		 WHERE parent_session_id = ? AND status IN ('done', 'failed')`).run(parentSessionId);
 }
-export function deleteToken(db, parentSessionId, runtimeIdentity) {
-    db.prepare("DELETE FROM tokens WHERE parent_session_id = ? AND runtime_identity = ?").run(parentSessionId, runtimeIdentity);
+/**
+ * Keeps only the newest `keep` queued events for one child. Events are advisory snapshots, so a
+ * parent that stopped reading must not leave an unbounded backlog behind.
+ */
+export function trimEventBacklog(db, parentSessionId, subagentId, keep) {
+    db.prepare(`DELETE FROM commands WHERE id IN (
+		   SELECT id FROM commands
+		   WHERE parent_session_id = ? AND subagent_id = ? AND direction = 'to_parent'
+		     AND operation = 'event' AND status = 'pending'
+		   ORDER BY created_at DESC
+		   LIMIT -1 OFFSET ?
+		 )`).run(parentSessionId, subagentId, keep);
 }

package/dist/state.js

@@ -32,6 +32,14 @@ function text(message) {
         .trim();
     return value === "" ? undefined : value;
 }
+/** Activity lines stay short. The full answer lives on the receipt, not in the dashboard summary. */
+const ACTIVITY_SUMMARY_LIMIT = 240;
+function activitySummary(value) {
+    const flat = value.replace(/\s+/g, " ").trim();
+    if (flat.length <= ACTIVITY_SUMMARY_LIMIT)
+        return flat;
+    return `${flat.slice(0, ACTIVITY_SUMMARY_LIMIT - 1)}…`;
+}
 function completed(message) {
     return message.stopReason !== "pending" && message.stopReason !== "deferred";
 }
@@ -83,7 +91,7 @@ export function summarizeCurrentBranch(entries) {
             continue;
         const value = text(item.message);
         if (value !== undefined)
-            return value;
+            return activitySummary(value);
     }
     return undefined;
 }
@@ -181,7 +189,7 @@ export function parseTranscriptFacts(value) {
         costUsd === undefined) {
         return undefined;
     }
-    const summary = typeof value.summary === "string" ? value.summary : undefined;
+    const summary = typeof value.summary === "string" ? activitySummary(value.summary) : undefined;
     const stopReason = typeof value.stopReason === "string" ? value.stopReason : undefined;
     const interrupted = typeof value.interrupted === "string" ? value.interrupted : undefined;
     const contextTokens = usageNumber(value.contextTokens);
@@ -297,7 +305,8 @@ export function createStateProjector(initialState = "running") {
                 const messages = Array.isArray(value.messages) ? value.messages : [];
                 const message = record(messages.length > 0 ? messages[messages.length - 1] : value.message);
                 if (message?.role === "assistant") {
-                    summary = text(message) ?? summary;
+                    const spoken = text(message);
+                    summary = spoken === undefined ? summary : activitySummary(spoken);
                     if (value.type === "agent_end" && message.stopReason === "error") {
                         state = "error";
                         interrupted = diagnostic(message);

package/dist/tool-activation.d.ts

@@ -1,10 +1,10 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { SubagentManager } from "./manager.js";
 /** Interactive agent tools managed by dynamic activation. */
-export declare const INTERACTIVE_TOOL_NAMES: readonly ["agent_spawn", "agent_send", "agent_get", "agent_stop"];
+export declare const INTERACTIVE_TOOL_NAMES: readonly ["agents_delegate", "agents_get", "agents_stop", "agents_dashboard"];
 export type InteractiveToolName = (typeof INTERACTIVE_TOOL_NAMES)[number];
 export declare const SUBAGENT_OPTIONAL_TOOL_KEY = "subagents";
-export declare const SUBAGENT_OPTIONAL_TOOL_BULLET = "subagents (query: \"agent\"): Subagent orchestration and delegation (agent_spawn, agent_send, agent_get, agent_stop).";
+export declare const SUBAGENT_OPTIONAL_TOOL_BULLET = "subagents (query: \"agent\"): Agent orchestration and delegation (agents_delegate, agents_get, agents_stop, agents_dashboard).";
 export interface RegisterInteractiveToolActivationOptions {
     readonly pi: ExtensionAPI;
     readonly manager: SubagentManager;

package/dist/tool-activation.js

@@ -1,13 +1,13 @@
 import { setOptionalToolBullet } from "@hheei/pi-ext-core";
 /** Interactive agent tools managed by dynamic activation. */
 export const INTERACTIVE_TOOL_NAMES = [
-    "agent_spawn",
-    "agent_send",
-    "agent_get",
-    "agent_stop",
+    "agents_delegate",
+    "agents_get",
+    "agents_stop",
+    "agents_dashboard",
 ];
 export const SUBAGENT_OPTIONAL_TOOL_KEY = "subagents";
-export const SUBAGENT_OPTIONAL_TOOL_BULLET = 'subagents (query: "agent"): Subagent orchestration and delegation (agent_spawn, agent_send, agent_get, agent_stop).';
+export const SUBAGENT_OPTIONAL_TOOL_BULLET = 'subagents (query: "agent"): Agent orchestration and delegation (agents_delegate, agents_get, agents_stop, agents_dashboard).';
 export function registerInteractiveToolActivation(options) {
     const { pi } = options;
     const unbindBeforeAgent = pi.on("before_agent_start", (event) => {

package/dist/tool-presentation.d.ts

@@ -1,14 +1,10 @@
 import type { ExtensionAPI, ToolRenderers } from "@earendil-works/pi-coding-agent";
-export interface AgentSpawnDetails {
-    readonly id: string;
-    readonly path: string;
-}
 /** One renderer set per tool, named exactly after its tool so nested calls resolve too. */
 export declare function parentToolRenderers(pi: ExtensionAPI): {
-    readonly spawn: ToolRenderers;
-    readonly send: ToolRenderers;
+    readonly delegate: ToolRenderers;
     readonly get: ToolRenderers;
     readonly stop: ToolRenderers;
+    readonly dashboard: ToolRenderers;
 };
 /** The child's blocker report names the reason in the header and keeps the full message readable. */
 export declare function contactParentRenderers(pi: ExtensionAPI): ToolRenderers;

package/dist/tool-presentation.js

@@ -14,150 +14,103 @@ function stringField(source, key) {
     const value = source?.[key];
     return typeof value === "string" && value.trim() !== "" ? value : undefined;
 }
-function numberField(source, key) {
-    const value = source[key];
-    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+function delegationDetails(result) {
+    const details = result?.details;
+    return isRecord(details) && typeof details.id === "string"
+        ? details
+        : undefined;
 }
-function spawnPresentation(args, result) {
+/** Readable delegation state; the result body is copied, never restated as state. */
+function delegationLines(view) {
+    const lines = [`status: ${view.status}`, `revision: ${view.revision}`];
+    if (view.progress !== undefined) {
+        lines.push(`runtime: ${view.progress.runtimeState}`);
+        if (view.progress.activeTool !== undefined)
+            lines.push(`activeTool: ${view.progress.activeTool}`);
+        if (view.progress.summary !== undefined)
+            lines.push(`summary: ${view.progress.summary}`);
+    }
+    lines.push(`hasOutput: ${String(view.hasOutput)}`);
+    if (view.error !== undefined)
+        lines.push(`error: ${view.error.reason}`);
+    return lines;
+}
+function delegationRow(view) {
+    const parts = [view.status];
+    if (view.agent !== undefined)
+        parts.push(view.agent);
+    if (view.progress !== undefined) {
+        parts.push(view.progress.activeTool ?? view.progress.runtimeState);
+    }
+    parts.push(`rev ${view.revision}`);
+    return parts.join(" · ");
+}
+function delegatePresentation(args, result) {
     const record = isRecord(args) ? args : undefined;
-    const agent = stringField(record, "agent") ?? "agent";
-    const title = stringField(record, "title");
+    const agent = stringField(record, "agent");
+    const id = stringField(record, "id");
     const task = stringField(record, "task");
-    const details = result !== undefined && isRecord(result.details) ? result.details : undefined;
-    const id = stringField(details, "id");
-    const path = stringField(details, "path");
-    const resultText = result === undefined ? undefined : agentResultText(result);
-    const rows = [
-        ...(id === undefined ? [] : [`id: ${id}`]),
-        ...(path === undefined ? [] : [`path: ${path}`]),
-    ];
-    const summaryParts = [agent];
-    if (title !== undefined && title.trim() !== "") {
-        summaryParts.push(title.trim());
+    const view = delegationDetails(result);
+    const resultText = view?.resultText;
+    const summaryParts = [view?.agent ?? agent ?? "agent"];
+    if (view !== undefined) {
+        summaryParts.push(view.id, `rev ${view.revision}`);
     }
-    if (id !== undefined && id.trim() !== "") {
-        summaryParts.push(id.trim());
+    else if (id !== undefined) {
+        summaryParts.push(id);
     }
+    const output = resultText ?? (view === undefined ? undefined : delegationLines(view).join("\n"));
     return {
         summary: summaryParts.join(" · "),
         ...(task === undefined ? {} : { request: task }),
+        ...(output === undefined ? {} : { output }),
         ...(task === undefined
             ? {}
-            : {
-                copy: {
-                    primary: task,
-                    full: resultText === undefined ? task : `${task}\n---\n${resultText}`,
-                },
-            }),
-        ...(rows.length === 0 ? {} : { output: rows.join("\n") }),
-    };
-}
-function sendPresentation(args, result) {
-    const record = isRecord(args) ? args : undefined;
-    const id = stringField(record, "id") ?? "agent";
-    const mode = stringField(record, "mode") ?? "steer";
-    const message = stringField(record, "message");
-    const confirmation = result === undefined ? undefined : agentResultText(result);
-    const copy = message === undefined
-        ? undefined
-        : {
-            primary: message,
-            ...(confirmation === undefined ? {} : { full: `${message}\n${confirmation}` }),
-        };
-    return {
-        summary: `${id} · ${mode}`,
-        ...(message === undefined ? {} : { request: message }),
-        ...(confirmation === undefined ? {} : { output: confirmation }),
-        ...(copy === undefined ? {} : { copy }),
+            : { copy: { primary: task, full: output === undefined ? task : `${task}\n---\n${output}` } }),
     };
 }
-const PROGRESS_TEXT_KEYS = ["agent", "path", "presentation", "freshness", "activeTool"];
-const PROGRESS_NUMBER_KEYS = ["turns", "tokens"];
-/** Readable selected fields only; never restates the task or a terminal answer. */
-function detailLines(details) {
-    const lines = [];
-    const status = stringField(details, "status");
-    if (status !== undefined)
-        lines.push(`status: ${status}`);
-    const progress = isRecord(details.progress) ? details.progress : undefined;
-    if (progress !== undefined) {
-        for (const key of PROGRESS_TEXT_KEYS) {
-            const value = stringField(progress, key);
-            if (value !== undefined)
-                lines.push(`${key}: ${value}`);
-        }
-        for (const key of PROGRESS_NUMBER_KEYS) {
-            const value = numberField(progress, key);
-            if (value !== undefined)
-                lines.push(`${key}: ${value}`);
-        }
-        const summary = stringField(progress, "summary");
-        if (summary !== undefined)
-            lines.push(`summary: ${summary}`);
-    }
-    const diagnostic = stringField(details, "diagnostic");
-    if (diagnostic !== undefined)
-        lines.push(`diagnostic: ${diagnostic}`);
-    return lines;
-}
-function getCollapsedRow(details) {
-    const parts = [];
-    const status = stringField(details, "status");
-    if (status !== undefined)
-        parts.push(status);
-    const progress = isRecord(details.progress) ? details.progress : undefined;
-    if (progress !== undefined) {
-        const agent = stringField(progress, "agent");
-        if (agent !== undefined)
-            parts.push(agent);
-        const turns = numberField(progress, "turns");
-        if (turns !== undefined)
-            parts.push(`${turns} turn${turns === 1 ? "" : "s"}`);
-        const tokens = numberField(progress, "tokens");
-        if (tokens !== undefined) {
-            const tokStr = tokens >= 1000 ? `${(tokens / 1000).toFixed(1).replace(/\.0$/u, "")}k` : String(tokens);
-            parts.push(`${tokStr} tok`);
-        }
-        const activeTool = stringField(progress, "activeTool");
-        if (activeTool !== undefined) {
-            parts.push(activeTool);
-        }
-        else {
-            const summary = stringField(progress, "summary");
-            if (summary !== undefined)
-                parts.push(summary.replace(/\s+/gu, " ").trim());
-        }
-    }
-    const diagnostic = stringField(details, "diagnostic");
-    if (diagnostic !== undefined) {
-        parts.push(`diagnostic: ${diagnostic.replace(/\s+/gu, " ").trim()}`);
-    }
-    return parts.length > 0 ? parts.join(" · ") : undefined;
-}
 function getPresentation(args, result) {
     const record = isRecord(args) ? args : undefined;
     const id = stringField(record, "id") ?? "agent";
-    const keys = stringField(record, "keys") ?? "status, progress";
-    const details = result !== undefined && isRecord(result.details) ? result.details : undefined;
-    const lines = details === undefined ? [] : detailLines(details);
-    const collapsedRow = details === undefined ? undefined : getCollapsedRow(details);
-    const resultText = result === undefined ? undefined : agentResultText(result);
+    const revision = record?.revision;
+    const view = delegationDetails(result);
+    const lines = view === undefined ? [] : delegationLines(view);
+    const resultText = view?.resultText;
     return {
-        summary: id,
-        request: `keys: ${keys}`,
+        summary: typeof revision === "number" ? `${id} · rev ${revision}` : id,
+        request: record?.includeOutput === true ? "with output" : "without output",
         ...(lines.length === 0 ? {} : { output: lines.join("\n") }),
-        ...(collapsedRow === undefined ? {} : { collapsedRows: [collapsedRow] }),
+        ...(view === undefined ? {} : { collapsedRows: [delegationRow(view)] }),
         ...(resultText === undefined ? {} : { copy: { primary: resultText } }),
     };
 }
 function stopPresentation(args, result) {
     const record = isRecord(args) ? args : undefined;
     const id = stringField(record, "id") ?? "agent";
+    const view = delegationDetails(result);
     const confirmation = result === undefined ? undefined : agentResultText(result);
+    const output = confirmation ?? (view === undefined ? undefined : `status: ${view.status}`);
     return {
         summary: id,
-        ...(confirmation === undefined ? {} : { output: confirmation }),
-        ...(confirmation === undefined ? {} : { copy: { primary: confirmation } }),
+        ...(output === undefined ? {} : { output }),
+        ...(output === undefined ? {} : { copy: { primary: output } }),
+    };
+}
+function dashboardPresentation(_args, result) {
+    const details = result?.details;
+    const view = isRecord(details) && Array.isArray(details.children)
+        ? details
+        : undefined;
+    if (view === undefined)
+        return { summary: "agents" };
+    const rows = view.children.map((child) => {
+        const agent = child.agent === undefined ? "" : ` (${child.agent})`;
+        const summary = child.summary === undefined ? "" : ` — ${child.summary}`;
+        return `- ${child.id}${agent}: ${child.runtimeState} / ${child.status} · rev ${child.revision}${summary}`;
+    });
+    return {
+        summary: `${view.total} agents · running ${view.running} · blocked ${view.blocked} · completed ${view.completed} · failed ${view.failed}`,
+        ...(rows.length === 0 ? {} : { output: rows.join("\n") }),
     };
 }
 function contactPresentation(args, result) {
@@ -181,10 +134,10 @@ function contactPresentation(args, result) {
 /** One renderer set per tool, named exactly after its tool so nested calls resolve too. */
 export function parentToolRenderers(pi) {
     return {
-        spawn: ownedRenderers(pi, "agent_spawn", spawnPresentation),
-        send: ownedRenderers(pi, "agent_send", sendPresentation),
-        get: ownedRenderers(pi, "agent_get", getPresentation),
-        stop: ownedRenderers(pi, "agent_stop", stopPresentation),
+        delegate: ownedRenderers(pi, "agents_delegate", delegatePresentation),
+        get: ownedRenderers(pi, "agents_get", getPresentation),
+        stop: ownedRenderers(pi, "agents_stop", stopPresentation),
+        dashboard: ownedRenderers(pi, "agents_dashboard", dashboardPresentation),
     };
 }
 /** The child's blocker report names the reason in the header and keeps the full message readable. */

package/dist/tools.d.ts

@@ -3,8 +3,6 @@ import type { DiscoveredAgent } from "./agent-resolver.js";
 import { type ChildIdentity } from "./domain.js";
 import type { SubagentManager } from "./manager.js";
 export declare function formatAvailableAgents(agents: readonly DiscoveredAgent[]): string;
-declare const GET_KEYS: readonly ["status", "progress", "diagnostic"];
-export type AgentGetKey = (typeof GET_KEYS)[number];
 export declare function registerParentTools(pi: ExtensionAPI, manager: SubagentManager, agents: readonly DiscoveredAgent[]): void;
 /** Sends a child-initiated request over the bridge and resolves with the parent's answer. */
 export type ChildReport = (operation: string, payload: unknown, signal?: AbortSignal) => Promise<unknown>;
@@ -14,4 +12,3 @@ export interface RegisterChildToolsOptions {
     readonly isBound?: (sessionId: string) => boolean;
 }
 export declare function registerChildTools(pi: ExtensionAPI, identity: ChildIdentity, options: RegisterChildToolsOptions): void;
-export {};