@hheei/pi-subagents 0.2.4 → 0.4.0

package/dist/mailbox.js

@@ -0,0 +1,368 @@
+import { randomUUID } from "node:crypto";
+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";
+const DEFAULT_POLL_MS = 50;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+export function createMailboxTransport(options) {
+    const db = openStateDb(options.filePath);
+    const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    const seen = new Set();
+    const eventListeners = new Set();
+    const connectionListeners = new Set();
+    let closed = false;
+    let polling = false;
+    const emitConnection = (childId, connected) => {
+        for (const listener of [...connectionListeners]) {
+            try {
+                listener(childId, connected);
+            }
+            catch (error) {
+                options.diagnose?.(`connection listener failed: ${errorMessage(error)}`);
+            }
+        }
+    };
+    const lockHeld = (childId) => {
+        const lockPath = processLockPath(options.filePath, options.parentSessionId, childId);
+        if (lockPath === undefined)
+            return false;
+        try {
+            return processLockHeld(lockPath);
+        }
+        catch (error) {
+            options.diagnose?.(`could not probe the process lock for ${childId}: ${errorMessage(error)}`);
+            return undefined;
+        }
+    };
+    const noticeLocks = () => {
+        if (closed)
+            return;
+        const directory = join(dirname(options.filePath), "locks", options.parentSessionId);
+        let names = [];
+        try {
+            names = readdirSync(directory);
+        }
+        catch (error) {
+            const missing = typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+            if (!missing) {
+                options.diagnose?.(`could not read process locks: ${errorMessage(error)}`);
+                return;
+            }
+        }
+        const heldNow = new Set();
+        for (const name of names) {
+            if (!name.endsWith(".lock"))
+                continue;
+            const childId = name.slice(0, -".lock".length);
+            const held = lockHeld(childId);
+            if (held === true || (held === undefined && seen.has(childId)))
+                heldNow.add(childId);
+        }
+        for (const childId of heldNow) {
+            if (seen.has(childId))
+                continue;
+            seen.add(childId);
+            emitConnection(childId, true);
+        }
+        for (const childId of [...seen]) {
+            if (heldNow.has(childId))
+                continue;
+            seen.delete(childId);
+            emitConnection(childId, false);
+        }
+    };
+    const takeParentCommands = async () => {
+        if (closed || polling)
+            return;
+        polling = true;
+        try {
+            noticeLocks();
+            // Empty is the common tick. A read sees it; claiming would take a write lock and fsync.
+            if (!hasPendingCommand(db, options.parentSessionId, "to_parent"))
+                return;
+            const claimed = withWrite(db, () => claimParentCommands(db, options.parentSessionId));
+            const eventIds = [];
+            const dropEvents = () => {
+                if (eventIds.length === 0)
+                    return;
+                const ids = eventIds.splice(0);
+                withWrite(db, () => {
+                    for (const id of ids)
+                        deleteCommand(db, id);
+                });
+            };
+            for (const command of claimed) {
+                if (!seen.has(command.subagentId) && lockHeld(command.subagentId) === true) {
+                    seen.add(command.subagentId);
+                    emitConnection(command.subagentId, true);
+                }
+                if (command.operation === "event") {
+                    let event = command.payload;
+                    try {
+                        event = JSON.parse(command.payload);
+                    }
+                    catch {
+                        event = command.payload;
+                    }
+                    for (const listener of [...eventListeners]) {
+                        try {
+                            listener(command.subagentId, event);
+                        }
+                        catch (error) {
+                            options.diagnose?.(`event listener failed: ${errorMessage(error)}`);
+                        }
+                    }
+                    eventIds.push(command.id);
+                    continue;
+                }
+                dropEvents();
+                try {
+                    const payload = JSON.parse(command.payload);
+                    const result = await options.handleRequest({
+                        childId: command.subagentId,
+                        operation: command.operation,
+                        payload,
+                    });
+                    finishCommand(db, command.id, { status: "done", result: JSON.stringify(result ?? null) });
+                }
+                catch (error) {
+                    const bridge = error instanceof BridgeError ? error : undefined;
+                    finishCommand(db, command.id, {
+                        status: "failed",
+                        errorCode: bridge?.code ?? "request_failed",
+                        error: bridge?.message ?? errorMessage(error),
+                    });
+                }
+            }
+            dropEvents();
+        }
+        finally {
+            polling = false;
+        }
+    };
+    withWrite(db, () => {
+        requeueAbandonedParentCommands(db, options.parentSessionId);
+    });
+    const timer = setInterval(() => {
+        void takeParentCommands();
+    }, pollMs);
+    timer.unref?.();
+    return {
+        endpoint: options.filePath,
+        isConnected(childId) {
+            return lockHeld(childId) !== false;
+        },
+        disconnect(childId) {
+            if (lockHeld(childId) !== false)
+                return;
+            if (seen.delete(childId))
+                emitConnection(childId, false);
+        },
+        async request(childId, operation, payload, requestOptions) {
+            const id = randomUUID();
+            enqueueCommand(db, {
+                id,
+                parentSessionId: options.parentSessionId,
+                subagentId: childId,
+                direction: "to_child",
+                operation,
+                payload: JSON.stringify(payload ?? null),
+                createdAt: Date.now(),
+            });
+            return waitForCommand(db, id, requestOptions?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, pollMs, requestOptions?.signal);
+        },
+        onEvent(listener) {
+            eventListeners.add(listener);
+            return () => {
+                eventListeners.delete(listener);
+            };
+        },
+        onConnectionChange(listener) {
+            connectionListeners.add(listener);
+            return () => {
+                connectionListeners.delete(listener);
+            };
+        },
+        async waitUntilSeen(childId, waitOptions) {
+            const timeoutMs = waitOptions?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+            const started = Date.now();
+            while (Date.now() - started < timeoutMs) {
+                if (waitOptions?.signal?.aborted)
+                    return false;
+                if (lockHeld(childId) === true) {
+                    if (!seen.has(childId)) {
+                        seen.add(childId);
+                        emitConnection(childId, true);
+                    }
+                    return true;
+                }
+                await delay(pollMs);
+            }
+            return false;
+        },
+        close() {
+            closed = true;
+            clearInterval(timer);
+        },
+    };
+}
+export function attachChildMailbox(options) {
+    let db;
+    let processLock;
+    const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    let closed = false;
+    let started = false;
+    let working = false;
+    let timer;
+    const database = () => {
+        if (db === undefined)
+            throw new BridgeError("not_connected", "the state database is not open");
+        return db;
+    };
+    const tick = async () => {
+        if (closed || working || db === undefined)
+            return;
+        working = true;
+        const current = db;
+        try {
+            if (!hasPendingCommand(current, options.parentSessionId, "to_child", options.subagentId)) {
+                return;
+            }
+            const command = withWrite(current, () => claimCommand(current, options.parentSessionId, options.subagentId, "to_child"));
+            if (command === undefined)
+                return;
+            await answer(current, command, options.handleRequest, options.diagnose);
+        }
+        finally {
+            working = false;
+        }
+    };
+    return {
+        get connected() {
+            return started && !closed;
+        },
+        start() {
+            if (started || closed)
+                return;
+            try {
+                db = openStateDb(options.filePath);
+                const lockPath = processLockPath(options.filePath, options.parentSessionId, options.subagentId);
+                if (lockPath === undefined)
+                    throw new Error("invalid process lock id");
+                processLock = holdProcessLock(lockPath);
+            }
+            catch (error) {
+                processLock?.release();
+                processLock = undefined;
+                db = undefined;
+                options.diagnose?.(`could not hold the child process lock: ${errorMessage(error)}`);
+                return;
+            }
+            started = true;
+            timer = setInterval(() => {
+                void tick();
+            }, pollMs);
+            timer.unref?.();
+            void tick();
+        },
+        report(operation, payload, signal) {
+            const current = database();
+            const id = randomUUID();
+            enqueueCommand(current, {
+                id,
+                parentSessionId: options.parentSessionId,
+                subagentId: options.subagentId,
+                direction: "to_parent",
+                operation,
+                payload: JSON.stringify(payload ?? null),
+                createdAt: Date.now(),
+            });
+            return waitForCommand(current, id, DEFAULT_REQUEST_TIMEOUT_MS, pollMs, signal);
+        },
+        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(),
+            });
+        },
+        close() {
+            closed = true;
+            started = false;
+            if (timer !== undefined)
+                clearInterval(timer);
+            processLock?.release();
+            processLock = undefined;
+        },
+    };
+}
+async function answer(db, command, handleRequest, diagnose) {
+    try {
+        const payload = JSON.parse(command.payload);
+        const result = await handleRequest({ operation: command.operation, payload });
+        finishCommand(db, command.id, { status: "done", result: JSON.stringify(result ?? null) });
+    }
+    catch (error) {
+        const bridge = error instanceof BridgeError ? error : undefined;
+        diagnose?.(`child command ${command.operation} failed: ${errorMessage(error)}`);
+        finishCommand(db, command.id, {
+            status: "failed",
+            errorCode: bridge?.code ?? "request_failed",
+            error: bridge?.message ?? errorMessage(error),
+        });
+    }
+}
+function waitForCommand(db, id, timeoutMs, pollMs, signal) {
+    const started = Date.now();
+    return new Promise((resolve, reject) => {
+        const timer = setInterval(() => {
+            if (signal?.aborted) {
+                clearInterval(timer);
+                withWrite(db, () => {
+                    deleteCommand(db, id);
+                });
+                reject(new BridgeError("aborted", "The mailbox request was cancelled"));
+                return;
+            }
+            const command = readCommand(db, id);
+            if (command === undefined)
+                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));
+                return;
+            }
+            if (command.status === "failed") {
+                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`));
+            }
+        }, pollMs);
+        timer.unref?.();
+    });
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}

package/dist/manager.d.ts

@@ -1,13 +1,13 @@
-import { type TaskRegistry } from "@hheei/pi-ext-core";
-import type { ChildRuntime } from "./child-process.js";
-import type { EffectiveLaunchConfig, OperationError, Presentation, PublicSubagent, SendMode, SpawnSubagentInput, SubagentRecord, SubagentState } from "./domain.js";
+import { type ChildRuntime } from "./child-process.js";
+import type { EffectiveLaunchConfig, OperationError, Presentation, PublicSubagent, RuntimeAttachment, SendMode, 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 { SubagentRegistry } from "./registry.js";
 import type { LaunchOutcome, RuntimeTokenStore } 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 `send_agent` starts it
+ * session lock, so an idle one is reclaimed after this window and a later `agent_send` starts it
  * again from the same session.
  */
 export declare const SUBAGENT_IDLE_TIMEOUT_MS = 15000;
@@ -44,7 +44,7 @@ export interface ChildBridgeTransport {
 }
 export interface ManagerDependencies {
     readonly parentSessionId: string;
-    readonly registry: Pick<SubagentRegistry, "get" | "list" | "update">;
+    readonly registry: Pick<SubagentRegistry, "get" | "list" | "update" | "path">;
     readonly resolve: (input: SpawnSubagentInput) => Promise<EffectiveLaunchConfig>;
     readonly bootstrap: (input: {
         readonly parentSessionId: string;
@@ -63,6 +63,13 @@ export interface ManagerDependencies {
     readonly presentation?: PresentationDeps;
     /** Waits for an already-running runtime to reconnect; false when it does not. */
     readonly connect: (record: SubagentRecord) => Promise<boolean>;
+    /**
+     * Host listing used to restore this session's panels before the next turn. Absent in tests that
+     * still exercise the bridge-only recover path.
+     */
+    readonly directory?: HostDirectory & {
+        rebind?(attachment: RuntimeAttachment): HostAttachment | undefined;
+    };
     readonly deadlineMs?: number;
     readonly settledCloseTimeoutMs?: number;
     readonly idleTimeoutMs?: number;
@@ -82,6 +89,7 @@ export interface PresentationDeps {
 }
 export interface SpawnResult {
     readonly child: PublicSubagent;
+    readonly path: string;
     /** Set when the child did not run where it would have by default. */
     readonly note?: string;
 }
@@ -99,14 +107,8 @@ export interface RecoveryResult {
 export declare function extractLastAssistantText(entries: readonly unknown[]): string | undefined;
 export declare class SubagentManager {
     #private;
-    bindTaskRegistry(registry: TaskRegistry): () => void;
     constructor(deps: ManagerDependencies);
-    /**
-     * Observes the raw bridge events of every child. A Task producer needs the child's
-     * `task_result` and settle events without also owning the bridge connection.
-     */
-    onChildEvent(listener: (childId: string, event: unknown) => void): () => void;
-    /** Presentation-only: widget and similar projections re-read list() after this. */
+    /** Presentation-only: status and similar projections re-read list() after this. */
     onChange(listener: () => void): () => void;
     dispose(): void;
     /**
@@ -115,7 +117,7 @@ export declare class SubagentManager {
      * not when extensions are reloaded.
      */
     closeLocalConnections(): void;
-    /** Reads a child's session entries; exposed for Task completion inspection. */
+    /** Reads a child's session entries; used by transcript inspection fallbacks. */
     getEntries(id: string): Promise<readonly unknown[] | undefined>;
     /**
      * Adopts the children that are still running. Nothing is launched here: a child that survived a
@@ -127,19 +129,17 @@ export declare class SubagentManager {
     send(id: string, rawMessage: string, mode?: SendMode, signal?: AbortSignal): Promise<OperationError | PublicSubagent>;
     get(id: string): Promise<PublicSubagent | OperationError>;
     list(): Promise<readonly PublicSubagent[]>;
-    /** Child startup and runs count until Pi settles, including post-agent_end continuation. */
-    get activeCount(): number;
     stop(id: string): Promise<OperationError | PublicSubagent>;
     contactParent(id: string, reason: string, message: string, knownRecord?: SubagentRecord): Promise<OperationError | {
         readonly delivered: true;
     }>;
-    /**
-     * Handles a request a child sent to its parent. The two child-initiated operations are the
-     * child's report channel and its Task result, and both are answered here so the child learns
-     * whether the parent accepted them.
-     */
+    /** Answers a request a child sent to its parent, so the child learns whether the parent accepted it. */
     handleChildRequest(childId: string, operation: string, payload: unknown): Promise<unknown>;
     /** Applies a bridge event to this child's record and notifies the raw child-event listeners. */
     handleEvent(childId: string, event: unknown): void;
     handleConnectionChange(childId: string, connected: boolean): void;
+    holdAttachment(id: string, attachment: HostAttachment): void;
+    /** Starts restoration. `before_agent_start` waits on `ready` so the turn sees the same ledger. */
+    reconcile(): Promise<LeaseReady>;
+    ready(): Promise<LeaseReady>;
 }