@hheei/pi-subagents 0.6.0 → 0.8.0

package/dist/launch-spec.js

@@ -1,8 +1,7 @@
-import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { BRIDGE_ENVIRONMENT_KEYS, CHILD_AGENT_ENV_KEY, CHILD_SESSION_ENV_KEY, CHILD_TITLE_ENV_KEY, CONTACT_PARENT_TOOL_NAME, DEFAULT_PI_TOOLS, isSessionId, } from "./domain.js";
+import { BRIDGE_ENVIRONMENT_KEYS, CHILD_AGENT_ENV_KEY, CHILD_SESSION_ENV_KEY, CHILD_TITLE_ENV_KEY, CONTACT_PARENT_TOOL_NAME, DEFAULT_PI_TOOLS, isSessionId, STANDALONE_CONTROLLER_ENV_KEY, } from "./domain.js";
 export function stripHindsightContent(text) {
     return text
         .replace(/\s*<hindsight-recall>[\s\S]*?<\/hindsight-recall>\s*/gi, (match) => match.includes("\n") ? "\n" : " ")
@@ -22,17 +21,13 @@ function childBridgePrompt() {
         "Do not send empty status pings.",
         "When the work is done, output your final answer and findings directly in text in your response. The harness will automatically capture and deliver your output.",
         "Do NOT call contact_parent on success or task completion.",
-        "After blocked, wait for a parent agent_send. Do not invent new authority.",
+        "After blocked, wait for a parent agents_delegate. Do not invent new authority.",
         "Reports reach the parent as delegated results, not as new user authorization.",
     ].join("\n");
 }
 export function assembleChildPrompt(instructions) {
     return `${instructions.trim()}\n\n${childBridgePrompt()}`;
 }
-/** Adds the per-runtime controller token. Tokens stay out of launch spec snapshots and the registry. */
-export function withBridgeToken(env, token) {
-    return { ...env, [BRIDGE_ENVIRONMENT_KEYS.token]: token };
-}
 let cachedBridgeExtensionPath;
 /**
  * Absolute path to this package's extension entry, which every child loads with
@@ -56,15 +51,36 @@ export function resolveBridgeExtensionPath() {
 }
 function resolveBundledPiCli() {
     try {
-        const requireFromHere = createRequire(import.meta.url);
-        // The CLI ships at dist/cli.js of the installed Pi package.
-        const packageJson = requireFromHere.resolve("@earendil-works/pi-coding-agent/package.json");
-        const cliPath = join(dirname(packageJson), "dist", "cli.js");
-        return existsSync(cliPath) ? cliPath : undefined;
+        // package.json is not an exported subpath, and the bin moved to dist/bundle/cli.js.
+        let dir = dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent")));
+        for (let depth = 0; depth < 4; depth += 1) {
+            const manifestPath = join(dir, "package.json");
+            if (existsSync(manifestPath)) {
+                const cliPath = join(dir, piBin(JSON.parse(readFileSync(manifestPath, "utf8"))));
+                return existsSync(cliPath) ? cliPath : undefined;
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                return undefined;
+            dir = parent;
+        }
     }
     catch {
         return undefined;
     }
+    return undefined;
+}
+function piBin(manifest) {
+    if (typeof manifest !== "object" || manifest === null || !("bin" in manifest)) {
+        throw new Error("Installed Pi package has no bin");
+    }
+    const bin = manifest.bin;
+    if (typeof bin === "string")
+        return bin;
+    if (typeof bin === "object" && bin !== null && "pi" in bin && typeof bin.pi === "string") {
+        return bin.pi;
+    }
+    throw new Error("Installed Pi package has no pi bin");
 }
 /**
  * Re-invokes the host Pi CLI instead of guessing a binary on PATH. Extensions load
@@ -85,7 +101,13 @@ export function resolvePiInvocation() {
     const execPath = process.execPath;
     const currentScript = process.argv[1];
     const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/") ?? false;
-    if (currentScript !== undefined && !isBunVirtualScript && existsSync(currentScript)) {
+    // The standalone controller is itself a node script. Reusing argv[1] would spawn another
+    // controller instead of Pi, so the child never opens the parent bridge.
+    const isControllerEntry = currentScript !== undefined && basename(currentScript).startsWith("controller-main.");
+    if (currentScript !== undefined &&
+        !isBunVirtualScript &&
+        !isControllerEntry &&
+        existsSync(currentScript)) {
         return { command: execPath, args: [currentScript] };
     }
     const execName = basename(execPath).toLowerCase();
@@ -171,8 +193,9 @@ export function buildLaunchSpec(options) {
         argv.push("--tools", Array.from(new Set(effectiveTools)).join(","));
     if (excludeTools.length > 0)
         argv.push("--exclude-tools", Array.from(new Set(excludeTools)).join(","));
-    if (!config.extensions.discovery)
+    if (!config.extensions.discovery || process.env[STANDALONE_CONTROLLER_ENV_KEY] === "1") {
         argv.push("--no-extensions");
+    }
     for (const path of config.extensions.paths)
         argv.push("-e", path);
     if (!config.skills.discovery)
@@ -192,6 +215,7 @@ export function buildLaunchSpec(options) {
         // Empty is the defined "derive the title in the child" case, mirroring the task channel below.
         [CHILD_TITLE_ENV_KEY]: config.title ?? "",
         PI_HINDSIGHT_DISABLE: "1",
+        PI_OBSERVATIONAL_MEMORY_DISABLE: "1",
         ...(config.codemodeOnly ? { PI_CODEMODE_MODE: "only" } : {}),
         ...(mcpExcluded && mcpExcluded.length > 0
             ? { PI_SUBAGENT_MCP_EXCLUDE: mcpExcluded.join(",") }

package/dist/lease.d.ts

@@ -73,7 +73,6 @@ export declare function createConversationLease(options: {
     readonly registry: RegistryStore;
     readonly hosts: HostDirectory;
     readonly processes: ProcessDirectory;
-    readonly forgetRuntime?: (runtimeIdentity: string) => void;
 }): ConversationLease;
 export declare function commitLease(registry: Pick<SubagentRegistry, "get" | "update">, id: string, edge: LeaseEdge, expectedRevision?: number, expectedRuntimeIdentity?: string): Promise<SubagentRecord>;
 /** `undefined` means the edge changes nothing, so the caller must not write. */

package/dist/lease.js

@@ -21,7 +21,7 @@ export const LEASE_EDGES = [
     "left-session",
 ];
 export function createConversationLease(options) {
-    const { registry, hosts, processes, forgetRuntime } = options;
+    const { registry, hosts, processes } = options;
     return {
         commit(id, edge, expectedRevision) {
             return commitLease(registry, id, edge, expectedRevision);
@@ -30,7 +30,7 @@ export function createConversationLease(options) {
             return registry.list();
         },
         ready() {
-            return reconcile(registry, hosts, processes, forgetRuntime);
+            return reconcile(registry, hosts, processes);
         },
     };
 }
@@ -126,7 +126,7 @@ function applyRuntimeGone(record, outcome) {
     const rest = record.runtime === undefined ? record : omitRuntime(record);
     return { ...rest, state: "done" };
 }
-async function reconcile(registry, hosts, processes, forgetRuntime) {
+async function reconcile(registry, hosts, processes) {
     const list = await hosts.list();
     if (!list.known)
         return { ok: false, reason: "unknown" };
@@ -147,7 +147,7 @@ async function reconcile(registry, hosts, processes, forgetRuntime) {
         }
         if (held)
             continue;
-        await releaseRuntime(registry, record, { type: "runtime-gone", outcome: "drop" }, forgetRuntime);
+        await releaseRuntime(registry, record, { type: "runtime-gone", outcome: "drop" });
         released.add(record.subagentId);
     }
     const records = all.filter((record) => !released.has(record.subagentId));
@@ -193,7 +193,7 @@ async function reconcile(registry, hosts, processes, forgetRuntime) {
                 await commitLease(registry, item.record.subagentId, { type: "stop-intent" });
                 stopped.push(item.record.subagentId);
             }
-            await releaseRuntime(registry, item.record, { type: "runtime-gone" }, forgetRuntime);
+            await releaseRuntime(registry, item.record, { type: "runtime-gone" });
         }
     }
     for (const record of records) {
@@ -204,7 +204,7 @@ async function reconcile(registry, hosts, processes, forgetRuntime) {
             rebound.push(record.subagentId);
             continue;
         }
-        await releaseRuntime(registry, record, { type: "runtime-gone", outcome: "drop" }, forgetRuntime);
+        await releaseRuntime(registry, record, { type: "runtime-gone", outcome: "drop" });
         released.add(record.subagentId);
     }
     if (!held && parentSessionId !== undefined && stored !== list.generation)
@@ -215,11 +215,8 @@ function panelId(record) {
     const attachment = record.runtime?.attachment;
     return attachment?.kind === "panel" ? attachment.id : undefined;
 }
-async function releaseRuntime(registry, record, edge, forgetRuntime) {
-    const identity = record.runtime?.runtimeIdentity;
-    const next = await commitLease(registry, record.subagentId, edge);
-    if (identity !== undefined && next.runtime === undefined)
-        forgetRuntime?.(identity);
+async function releaseRuntime(registry, record, edge) {
+    await commitLease(registry, record.subagentId, edge);
 }
 function omitRuntime(record) {
     const { runtime: _runtime, ...rest } = record;

package/dist/mailbox.js

@@ -3,8 +3,8 @@ import { readdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { errorMessage } from "@hheei/pi-ext-core";
 import { holdProcessLock, processLockHeld, processLockPath, } from "./process-lock.js";
-import { BridgeError } from "./protocol.js";
-import { claimCommand, claimParentCommands, deleteCommand, enqueueCommand, finishCommand, hasPendingCommand, openStateDb, readCommand, requeueAbandonedParentCommands, withWrite, } from "./state-db.js";
+import { BridgeError, DEFAULT_MAX_BUFFERED_EVENTS } from "./protocol.js";
+import { claimCommand, claimParentCommands, deleteCommand, deleteSettledCommands, enqueueCommand, finishCommand, hasPendingCommand, openStateDb, readCommand, requeueAbandonedParentCommands, trimEventBacklog, withWrite, } from "./state-db.js";
 const DEFAULT_POLL_MS = 50;
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 export function createMailboxTransport(options) {
@@ -13,6 +13,8 @@ export function createMailboxTransport(options) {
     const seen = new Set();
     const eventListeners = new Set();
     const connectionListeners = new Set();
+    /** One lifetime per transport: closing it settles every request still waiting on a reply. */
+    const lifetime = new AbortController();
     let closed = false;
     let polling = false;
     const emitConnection = (childId, connected) => {
@@ -145,9 +147,12 @@ export function createMailboxTransport(options) {
     };
     withWrite(db, () => {
         requeueAbandonedParentCommands(db, options.parentSessionId);
+        deleteSettledCommands(db, options.parentSessionId);
     });
     const timer = setInterval(() => {
-        void takeParentCommands();
+        void takeParentCommands().catch((error) => {
+            options.diagnose?.(`could not take parent commands: ${errorMessage(error)}`);
+        });
     }, pollMs);
     timer.unref?.();
     return {
@@ -172,7 +177,12 @@ export function createMailboxTransport(options) {
                 payload: JSON.stringify(payload ?? null),
                 createdAt: Date.now(),
             });
-            return waitForCommand(db, id, requestOptions?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, pollMs, requestOptions?.signal);
+            return waitForCommand(db, id, {
+                timeoutMs: requestOptions?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+                pollMs,
+                signal: untilClosed(requestOptions?.signal, lifetime.signal),
+                ...(options.diagnose === undefined ? {} : { diagnose: options.diagnose }),
+            });
         },
         onEvent(listener) {
             eventListeners.add(listener);
@@ -206,6 +216,7 @@ export function createMailboxTransport(options) {
         close() {
             closed = true;
             clearInterval(timer);
+            lifetime.abort(new BridgeError("closed", "The mailbox transport was closed"));
         },
     };
 }
@@ -213,6 +224,7 @@ export function attachChildMailbox(options) {
     let db;
     let processLock;
     const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    const lifetime = new AbortController();
     let closed = false;
     let started = false;
     let working = false;
@@ -263,10 +275,14 @@ export function attachChildMailbox(options) {
             }
             started = true;
             timer = setInterval(() => {
-                void tick();
+                void tick().catch((error) => {
+                    options.diagnose?.(`could not take a parent command: ${errorMessage(error)}`);
+                });
             }, pollMs);
             timer.unref?.();
-            void tick();
+            void tick().catch((error) => {
+                options.diagnose?.(`could not take a parent command: ${errorMessage(error)}`);
+            });
         },
         report(operation, payload, signal) {
             const current = database();
@@ -280,27 +296,42 @@ export function attachChildMailbox(options) {
                 payload: JSON.stringify(payload ?? null),
                 createdAt: Date.now(),
             });
-            return waitForCommand(current, id, DEFAULT_REQUEST_TIMEOUT_MS, pollMs, signal);
+            return waitForCommand(current, id, {
+                timeoutMs: DEFAULT_REQUEST_TIMEOUT_MS,
+                pollMs,
+                signal: untilClosed(signal, lifetime.signal),
+                ...(options.diagnose === undefined ? {} : { diagnose: options.diagnose }),
+            });
         },
         sendEvent(event) {
             if (db === undefined)
                 return;
             const current = db;
-            enqueueCommand(current, {
-                id: randomUUID(),
-                parentSessionId: options.parentSessionId,
-                subagentId: options.subagentId,
-                direction: "to_parent",
-                operation: "event",
-                payload: JSON.stringify(event ?? null),
-                createdAt: Date.now(),
-            });
+            try {
+                withWrite(current, () => {
+                    enqueueCommand(current, {
+                        id: randomUUID(),
+                        parentSessionId: options.parentSessionId,
+                        subagentId: options.subagentId,
+                        direction: "to_parent",
+                        operation: "event",
+                        payload: JSON.stringify(event ?? null),
+                        createdAt: Date.now(),
+                    });
+                    trimEventBacklog(current, options.parentSessionId, options.subagentId, DEFAULT_MAX_BUFFERED_EVENTS);
+                });
+            }
+            catch (error) {
+                // An advisory frame is never worth failing a turn over.
+                options.diagnose?.(`could not queue an event: ${errorMessage(error)}`);
+            }
         },
         close() {
             closed = true;
             started = false;
             if (timer !== undefined)
                 clearInterval(timer);
+            lifetime.abort(new BridgeError("closed", "The child mailbox was closed"));
             processLock?.release();
             processLock = undefined;
         },
@@ -322,44 +353,89 @@ async function answer(db, command, handleRequest, diagnose) {
         });
     }
 }
-function waitForCommand(db, id, timeoutMs, pollMs, signal) {
+function waitForCommand(db, id, options) {
     const started = Date.now();
     return new Promise((resolve, reject) => {
-        const timer = setInterval(() => {
-            if (signal?.aborted) {
-                clearInterval(timer);
+        const drop = () => {
+            try {
                 withWrite(db, () => {
                     deleteCommand(db, id);
                 });
-                reject(new BridgeError("aborted", "The mailbox request was cancelled"));
+            }
+            catch (error) {
+                options.diagnose?.(`could not drop command ${id}: ${errorMessage(error)}`);
+            }
+        };
+        const finish = () => {
+            clearInterval(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            finish();
+            drop();
+            reject(abortReason(options.signal));
+        };
+        const timer = setInterval(() => {
+            // The deadline is read before the row, so a row another writer deleted can never leave
+            // this waiter polling forever.
+            const expired = Date.now() - started >= options.timeoutMs;
+            let command;
+            try {
+                command = readCommand(db, id);
+            }
+            catch (error) {
+                finish();
+                reject(new BridgeError("state_unavailable", errorMessage(error)));
                 return;
             }
-            const command = readCommand(db, id);
-            if (command === undefined)
+            if (command === undefined) {
+                if (!expired)
+                    return;
+                finish();
+                reject(new BridgeError("timeout", `No answer for ${id} after ${options.timeoutMs}ms`));
                 return;
-            if (command.status === "done" ||
-                command.status === "failed" ||
-                Date.now() - started >= timeoutMs) {
-                clearInterval(timer);
-                withWrite(db, () => {
-                    deleteCommand(db, command.id);
-                });
             }
             if (command.status === "done") {
-                resolve(command.result === null ? null : JSON.parse(command.result));
+                finish();
+                drop();
+                try {
+                    resolve(command.result === null ? null : JSON.parse(command.result));
+                }
+                catch (error) {
+                    reject(new BridgeError("malformed_result", errorMessage(error)));
+                }
                 return;
             }
             if (command.status === "failed") {
+                finish();
+                drop();
                 reject(new BridgeError(command.errorCode ?? "request_failed", command.error ?? "The command failed"));
                 return;
             }
-            if (Date.now() - started >= timeoutMs) {
-                reject(new BridgeError("timeout", `No answer for ${id} after ${timeoutMs}ms`));
+            if (expired) {
+                finish();
+                drop();
+                reject(new BridgeError("timeout", `No answer for ${id} after ${options.timeoutMs}ms`));
             }
-        }, pollMs);
+        }, options.pollMs);
         timer.unref?.();
+        if (options.signal?.aborted === true) {
+            onAbort();
+            return;
+        }
+        options.signal?.addEventListener("abort", onAbort, { once: true });
     });
 }
+/** A caller's own cancellation and this transport's lifetime both settle a waiting request. */
+function untilClosed(signal, lifetime) {
+    return signal === undefined ? lifetime : AbortSignal.any([signal, lifetime]);
+}
+function abortReason(signal) {
+    const reason = signal?.reason;
+    if (reason instanceof BridgeError)
+        return reason;
+    return new BridgeError("aborted", "The mailbox request was cancelled");
+}
 function delay(ms) {
     return new Promise((resolve) => {
         const timer = setTimeout(resolve, ms);

package/dist/manager.d.ts

@@ -1,13 +1,15 @@
 import { type ChildRuntime } from "./child-process.js";
-import type { EffectiveLaunchConfig, OperationError, Presentation, PublicSubagent, RuntimeAttachment, SendMode, SpawnSubagentInput, SubagentRecord, SubagentState } from "./domain.js";
+import { type DashboardView, type DelegationView } from "./delegation.js";
+import type { DelegateSubagentInput, EffectiveLaunchConfig, OperationError, Presentation, PublicSubagent, RuntimeAttachment, SpawnSubagentInput, SubagentRecord, SubagentState } from "./domain.js";
 import type { HostAttachment } from "./host-adapter.js";
 import type { HostDirectory, LeaseReady } from "./lease.js";
 import { type BridgeOperation } from "./protocol.js";
+import { type ReceiptSettlement } from "./receipts.js";
 import type { SubagentRegistry } from "./registry.js";
-import type { LaunchOutcome, RuntimeTokenStore } from "./runtime.js";
+import type { LaunchOutcome } from "./runtime.js";
 /**
  * How long an idle child keeps its runtime. A background child holds a whole Pi process and its
- * session lock, so an idle one is reclaimed after this window and a later `agent_send` starts it
+ * session lock, so an idle one is reclaimed after this window and a later `agents_delegate` starts it
  * again from the same session.
  */
 export declare const SUBAGENT_IDLE_TIMEOUT_MS = 15000;
@@ -75,7 +77,6 @@ export interface ManagerDependencies {
     readonly idleTimeoutMs?: number;
     readonly failedPanelCloseTimeoutMs?: number;
     readonly channel?: ParentChannel;
-    readonly tokens?: RuntimeTokenStore;
 }
 /**
  * How this parent presents children, as the manager needs it: something that opens a panel for a
@@ -93,6 +94,18 @@ export interface SpawnResult {
     /** Set when the child did not run where it would have by default. */
     readonly note?: string;
 }
+/** Accepted dispatch, not a completed turn. Future MCP Tasks bind a receipt to this submission. */
+export interface DelegationSubmission {
+    readonly child: PublicSubagent;
+    readonly action: "spawn" | "reuse";
+    readonly note?: string;
+    /** Pi work version that may settle this input. Same-turn steers share one version. */
+    readonly workVersion?: number;
+    /** The compaction this input controls; such an input never opens a turn. */
+    readonly controlId?: string;
+    /** Set when that version already settled before the receipt row was written. */
+    readonly settled?: ReceiptSettlement;
+}
 export interface RecoveryResult {
     readonly recovered: readonly string[];
     readonly failures: readonly {
@@ -118,16 +131,49 @@ export declare class SubagentManager {
      */
     closeLocalConnections(): void;
     /** Reads a child's session entries; used by transcript inspection fallbacks. */
-    getEntries(id: string): Promise<readonly unknown[] | undefined>;
+    getEntries(id: string, range?: {
+        readonly cursor?: number;
+        readonly limit?: number;
+    }): Promise<{
+        readonly entries: readonly unknown[];
+        readonly nextCursor?: number;
+    } | undefined>;
     /**
      * Adopts the children that are still running. Nothing is launched here: a child that survived a
      * parent restart reconnects its bridge by itself, and a child that did not is simply not live
      * until a later send starts it from its recorded session.
      */
     recover(): Promise<RecoveryResult>;
+    /**
+     * One dispatch path for MCP's new-child and existing-child forms. This only confirms input
+     * delivery; waiting for the specific turn's final report belongs to the MCP delegation receipt,
+     * not to spawn/send or the child's durable identity.
+     */
+    submitDelegation(input: DelegateSubagentInput, onTarget?: (childId: string) => void): Promise<DelegationSubmission | OperationError>;
+    /**
+     * The acceptance path both consumers share: reserve this delegation's revision, dispatch it into
+     * the agent session, then either wait for that revision's settlement or return its identity.
+     * Waiting never holds the per-agent chain, so settlements and later steers still get in.
+     */
+    delegate(input: DelegateSubagentInput & {
+        readonly wait?: boolean;
+    }, signal?: AbortSignal, onAccepted?: (view: DelegationView) => void): Promise<DelegationView | OperationError>;
     spawn(input: SpawnSubagentInput): Promise<SpawnResult | OperationError>;
-    send(id: string, rawMessage: string, mode?: SendMode, signal?: AbortSignal): Promise<OperationError | PublicSubagent>;
+    send(id: string, rawMessage: string, signal?: AbortSignal): Promise<OperationError | PublicSubagent>;
     get(id: string): Promise<PublicSubagent | OperationError>;
+    /**
+     * One delegation of one agent, by revision: the newest by default. The result body is only read
+     * when it is asked for, and then only within the shared output budget.
+     */
+    inspect(input: {
+        readonly id: string;
+        readonly revision?: number;
+        readonly includeOutput?: boolean;
+    }): Promise<DelegationView | OperationError>;
+    /** Every agent of this parent: runtime state now, latest delegation status, no result bodies. */
+    dashboard(): Promise<DashboardView>;
+    /** Stops the runtime and reports the same projection every other read returns. */
+    stopAgent(id: string): Promise<DelegationView | OperationError>;
     list(): Promise<readonly PublicSubagent[]>;
     stop(id: string): Promise<OperationError | PublicSubagent>;
     contactParent(id: string, reason: string, message: string, knownRecord?: SubagentRecord): Promise<OperationError | {