@hheei/pi-subagents 0.1.2 → 0.2.2

package/dist/child-bridge.d.ts

@@ -2,26 +2,16 @@
  * Child-branch session binding. The TUI process may /reload the same session,
  * /quit, or switch to an unrelated session B. Only a confirmed leave of A
  * unbinds the bridge; shutdown or switch requests alone do not.
+ *
+ * Everything the parent asks of this child arrives over the bridge connection created here, and
+ * every Pi event, lifecycle notice and report this child produces leaves over that same connection.
  */
-import type { ExtensionAPI, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, SessionShutdownEvent, SessionStartEvent } from "@earendil-works/pi-coding-agent";
 import type { ChildIdentity } from "./domain.js";
-import { PauseGate } from "./pause-gate.js";
 export type ChildLifecycleKind = "left_session" | "tui_quit" | "user_interrupt";
 export interface ChildBridgeState {
     bound: boolean;
     boundSessionId: string;
-    readonly gate: PauseGate;
-}
-export interface ChildPauseSocket {
-    connect?(signal?: AbortSignal): Promise<void>;
-    reportPaused(generation: number, signal?: AbortSignal): Promise<void>;
-    onEvent(listener: (event: unknown) => void): () => void;
-    close(): void;
-}
-export interface ChildBridgeOptions {
-    readonly pauseSocket?: ChildPauseSocket;
-    readonly gate?: PauseGate;
-    readonly connect?: (socket: ChildPauseSocket, signal?: AbortSignal) => Promise<void>;
 }
 export declare function boundSessionIdFromEnv(env?: NodeJS.ProcessEnv): string | undefined;
 export declare function shouldLeaveBoundSession(params: {
@@ -29,6 +19,28 @@ export declare function shouldLeaveBoundSession(params: {
     readonly currentSessionId: string;
     readonly reason: SessionStartEvent["reason"];
 }): boolean;
+/**
+ * The child's session title. A delegated session is kept out of the human's session list by
+ * writing it into the child-scoped session directory; this title is what identifies the session
+ * when someone opens a child session deliberately.
+ */
+export declare function childSessionTitle(params: {
+    /** Title requested at spawn; an absent or empty one is derived from the child itself. */
+    readonly title: string | undefined;
+    readonly subagentId: string;
+    readonly agent: string;
+}): string;
+/** Only a session a human operates owns a user-visible quit. */
+/**
+ * The shutdown reasons that end this process's bridge connection. A reload loads this extension
+ * again in a fresh instance: the old client has to stop dialing, or two clients would compete for
+ * one bridge connection. The session binding survives either way.
+ */
+export declare function shouldDisposeBridge(reason: SessionShutdownEvent["reason"]): boolean;
+export declare function shouldReportTuiQuit(params: {
+    readonly reason: SessionShutdownEvent["reason"];
+    readonly mode: ExtensionContext["mode"];
+}): boolean;
 export declare function isConfirmedUserInterrupt(messages: readonly {
     role?: string;
     stopReason?: string;
@@ -37,5 +49,9 @@ export declare function lastActivityText(messages: readonly {
     role?: string;
     content?: unknown;
 }[] | undefined): string;
-/** Registers the child-only tools, identity widget, and session-leave reporting. */
+export interface ChildBridgeOptions {
+    /** Where connection problems are reported; defaults to this process's stderr. */
+    readonly diagnose?: (message: string) => void;
+}
+/** Registers the child-only tools, identity widget, bridge control plane and session reporting. */
 export declare function registerChildBridge(pi: ExtensionAPI, identity: ChildIdentity, options?: ChildBridgeOptions): ChildBridgeState;

package/dist/child-bridge.js

@@ -1,10 +1,7 @@
-import { registerChildNudge } from "./child-nudge.js";
-import { connectWithRetry, RunnerConnection, sendLifecycleToRunner } from "./connector.js";
-import { CHILD_AGENT_ENV_KEY, CHILD_SESSION_ENV_KEY, isRecord } from "./domain.js";
-import { PauseGate } from "./pause-gate.js";
-import { CANCEL_PAUSE_EVENT, PAUSE_EVENT } from "./protocol.js";
+import { isRecord } from "@hheei/pi-ext-core";
+import { registerChildControl } from "./child-control.js";
+import { CHILD_AGENT_ENV_KEY, CHILD_SESSION_ENV_KEY, CHILD_TITLE_ENV_KEY } from "./domain.js";
 import { registerChildTools } from "./tools.js";
-import { createChildIdentityWidget } from "./widget.js";
 const USER_INTERRUPT_STOP_REASON = "aborted";
 export function boundSessionIdFromEnv(env = process.env) {
     const value = env[CHILD_SESSION_ENV_KEY];
@@ -15,6 +12,34 @@ export function shouldLeaveBoundSession(params) {
         return false;
     return params.reason === "new" || params.reason === "resume" || params.reason === "fork";
 }
+/** Every delegated session title carries this marker, so a child session is recognizable at a glance. */
+const SUBAGENT_TITLE_MARKER = "🤖";
+/**
+ * The child's session title. A delegated session is kept out of the human's session list by
+ * writing it into the child-scoped session directory; this title is what identifies the session
+ * when someone opens a child session deliberately.
+ */
+export function childSessionTitle(params) {
+    const title = params.title?.trim();
+    if (title !== undefined && title !== "")
+        return `${SUBAGENT_TITLE_MARKER} ${title}`;
+    const agent = params.agent.trim();
+    return agent === ""
+        ? `${SUBAGENT_TITLE_MARKER} ${params.subagentId}`
+        : `${SUBAGENT_TITLE_MARKER} ${agent} · ${params.subagentId}`;
+}
+/** Only a session a human operates owns a user-visible quit. */
+/**
+ * The shutdown reasons that end this process's bridge connection. A reload loads this extension
+ * again in a fresh instance: the old client has to stop dialing, or two clients would compete for
+ * one bridge connection. The session binding survives either way.
+ */
+export function shouldDisposeBridge(reason) {
+    return reason === "quit" || reason === "reload";
+}
+export function shouldReportTuiQuit(params) {
+    return params.reason === "quit" && params.mode === "tui";
+}
 export function isConfirmedUserInterrupt(messages) {
     if (messages === undefined)
         return false;
@@ -53,81 +78,80 @@ function messageText(content) {
 function currentSessionId(ctx) {
     return ctx.sessionManager.getSessionId();
 }
-function reportLifecycle(identity, kind, sessionId, message) {
-    void sendLifecycleToRunner(identity, {
-        type: "child_lifecycle",
-        parentSessionId: identity.parentSessionId,
-        childId: identity.subagentId,
-        runtimeIdentity: identity.runtimeIdentity,
-        kind,
-        sessionId,
-        ...(message === undefined || message === "" ? {} : { message }),
-    }).catch((error) => {
-        console.error(`pi-subagents: failed to report ${kind}: ${error instanceof Error ? error.message : String(error)}`);
-    });
-}
-/** Registers the child-only tools, identity widget, and session-leave reporting. */
+/** Registers the child-only tools, identity widget, bridge control plane and session reporting. */
 export function registerChildBridge(pi, identity, options = {}) {
     const boundSessionId = boundSessionIdFromEnv() ?? "";
-    const gate = options.gate ?? new PauseGate();
     const state = {
         bound: boundSessionId !== "",
         boundSessionId,
-        gate,
     };
-    const nudge = registerChildNudge(pi);
+    const isBound = (sessionId) => state.bound && (state.boundSessionId === "" || sessionId === state.boundSessionId);
+    const control = registerChildControl(pi, {
+        endpoint: identity.endpoint,
+        identity,
+        isActive: () => state.bound,
+        diagnose: options.diagnose ??
+            ((message) => {
+                if (process.env.DEBUG || process.env.PI_SUBAGENTS_DEBUG) {
+                    console.error(`pi-subagents: ${message}`);
+                }
+            }),
+    });
+    const report = async (operation, payload, signal) => await control.report(operation, payload, signal);
     registerChildTools(pi, identity, {
-        onReport: () => nudge.markReported(),
-        isBound: (sessionId) => state.bound && (state.boundSessionId === "" || sessionId === state.boundSessionId),
+        report,
+        isBound,
     });
     const stop = new AbortController();
-    const pauseSocket = options.pauseSocket ?? openChildPauseSocket(identity);
-    pauseSocket.onEvent((event) => {
-        if (!isRecord(event) || typeof event.type !== "string")
-            return;
-        if (event.type === PAUSE_EVENT && typeof event.generation === "number") {
-            gate.request(event.generation);
-            return;
-        }
-        if (event.type === CANCEL_PAUSE_EVENT) {
-            gate.cancel(typeof event.generation === "number" ? event.generation : undefined);
-        }
-    });
-    const connectPause = options.connect ?? defaultConnectPause;
-    void connectPause(pauseSocket, stop.signal).catch((error) => {
-        console.error(`pi-subagents: pause bridge failed: ${error instanceof Error ? error.message : String(error)}`);
-    });
-    let identityWidget;
-    const disposeWidget = () => {
-        identityWidget?.dispose();
-        identityWidget = undefined;
-    };
-    const showIdentity = (ctx) => {
-        disposeWidget();
-        if (!state.bound || ctx.mode !== "tui")
-            return;
-        const tools = pi.getAllTools();
-        identityWidget = createChildIdentityWidget(pi, ctx, stop.signal, {
-            agent: process.env[CHILD_AGENT_ENV_KEY] ?? "",
-            toolCount: tools.length,
+    const reportLifecycle = (kind, sessionId, message) => {
+        control.sendEvent({
+            type: "child_lifecycle",
+            parentSessionId: identity.parentSessionId,
+            childId: identity.subagentId,
+            runtimeIdentity: identity.runtimeIdentity,
+            kind,
+            sessionId,
+            ...(message === undefined || message === "" ? {} : { message }),
         });
     };
     const leave = (sessionId) => {
         if (!state.bound)
             return;
         state.bound = false;
-        gate.cancel();
-        pauseSocket.close();
-        disposeWidget();
-        nudge.dispose();
-        reportLifecycle(identity, "left_session", sessionId);
+        reportLifecycle("left_session", sessionId);
+        // This process serves another session from now on, so it is never this child again: closing the
+        // bridge for good is what keeps a parent that missed the notice (its socket was down, or it
+        // restarted) from adopting this process — and later stopping the panel the human is using.
+        control.dispose();
+    };
+    /**
+     * A launch already knows which session it was started for, so the title is written the first
+     * time this process sees that session. One write per session is enough: the name lives in the
+     * session file, and re-appending it on every reload would only add entries.
+     */
+    let titledSessionId = "";
+    const titleSession = (sessionId) => {
+        if (titledSessionId === sessionId)
+            return;
+        titledSessionId = sessionId;
+        pi.setSessionName(childSessionTitle({
+            title: process.env[CHILD_TITLE_ENV_KEY],
+            subagentId: identity.subagentId,
+            agent: process.env[CHILD_AGENT_ENV_KEY] ?? "",
+        }));
     };
     pi.on("session_start", (event, ctx) => {
         const sessionId = currentSessionId(ctx);
+        // Connecting here is what makes a live bridge mean a live session: the parent's first request
+        // can never arrive before this process has a session to answer it with.
+        control.start(ctx);
+        if (ctx.ui?.setToolsExpanded) {
+            ctx.ui.setToolsExpanded(false);
+        }
         if (!state.bound && state.boundSessionId === "") {
             state.boundSessionId = sessionId;
             state.bound = true;
-            showIdentity(ctx);
+            titleSession(sessionId);
             return;
         }
         if (shouldLeaveBoundSession({
@@ -138,24 +162,19 @@ export function registerChildBridge(pi, identity, options = {}) {
             leave(sessionId);
             return;
         }
-        if (state.bound && sessionId === state.boundSessionId)
-            showIdentity(ctx);
-    });
-    pi.on("session_shutdown", (event) => {
-        if (event.reason === "quit" && state.bound) {
-            reportLifecycle(identity, "tui_quit", state.boundSessionId);
+        if (state.bound && sessionId === state.boundSessionId) {
+            titleSession(sessionId);
         }
-        disposeWidget();
-        if (event.reason === "quit" ||
-            event.reason === "new" ||
-            event.reason === "resume" ||
-            event.reason === "fork") {
-            nudge.dispose();
+    });
+    pi.on("session_shutdown", (event, ctx) => {
+        if (state.bound && shouldReportTuiQuit({ reason: event.reason, mode: ctx.mode })) {
+            reportLifecycle("tui_quit", state.boundSessionId);
         }
-        if (event.reason === "quit") {
-            gate.cancel();
-            pauseSocket.close();
+        if (shouldDisposeBridge(event.reason)) {
+            // The process is going away (quit) or this extension is about to be loaded again (reload):
+            // either way this client stops dialing, and the reloaded bridge serves the same session.
             stop.abort();
+            control.dispose();
         }
     });
     pi.on("agent_end", (event, ctx) => {
@@ -165,50 +184,9 @@ export function registerChildBridge(pi, identity, options = {}) {
         if (!isConfirmedUserInterrupt(messages))
             return;
         const activity = lastActivityText(messages);
-        reportLifecycle(identity, "user_interrupt", state.boundSessionId, activity === ""
+        reportLifecycle("user_interrupt", state.boundSessionId, activity === ""
             ? "Task is unfinished and waiting for user intent."
             : `Task is unfinished and waiting for user intent. Last activity: ${activity}`);
     });
-    pi.on("turn_end", async () => {
-        if (!state.bound || !gate.holding)
-            return;
-        const generation = gate.generation;
-        try {
-            await pauseSocket.reportPaused(generation, stop.signal);
-        }
-        catch (error) {
-            if (stop.signal.aborted)
-                return;
-            console.error(`pi-subagents: failed to ack pause: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        await gate.wait(stop.signal);
-    });
     return state;
 }
-function openChildPauseSocket(identity) {
-    const connection = new RunnerConnection({
-        endpoint: identity.endpoint,
-        identity,
-        token: identity.token,
-        role: "bridge",
-    });
-    return {
-        connect: (signal) => connection.connect(signal),
-        async reportPaused(generation, signal) {
-            await connection.request("report_paused", {
-                type: "report_paused",
-                parentSessionId: identity.parentSessionId,
-                childId: identity.subagentId,
-                runtimeIdentity: identity.runtimeIdentity,
-                generation,
-            }, signal === undefined ? {} : { signal });
-        },
-        onEvent: (listener) => connection.onEvent(listener),
-        close: () => connection.close(),
-    };
-}
-async function defaultConnectPause(socket, signal) {
-    if (socket.connect === undefined)
-        return;
-    await connectWithRetry({ connect: (abort) => socket.connect?.(abort) ?? Promise.resolve() }, signal === undefined ? {} : { signal });
-}

package/dist/child-control.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Child-side control plane.
+ *
+ * The parent drives a child, and the child reports back, over one bridge connection. Every parent
+ * request is executed with this process's own Pi primitives, so a child presented in a host panel
+ * and a child running headless are controlled identically and no second transport (an RPC writer,
+ * a pause handshake) has to be kept in sync with the child's real state.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ChildIdentity } from "./domain.js";
+import { type ChildInputSource } from "./protocol.js";
+export interface ChildControl {
+    /**
+     * Opens the bridge connection for the session this process is now serving. Called from
+     * `session_start`, so a connected bridge always means a live, ready child session.
+     */
+    start(context?: ExtensionContext): void;
+    /**
+     * Sends a report the parent must acknowledge: `contact_parent`, `task_result`. An aborted
+     * signal gives up on it, so a cancelled tool call does not wait for an unreachable parent.
+     */
+    report(operation: string, payload: unknown, signal?: AbortSignal): Promise<unknown>;
+    /** Sends an advisory frame: child lifecycle signals. */
+    sendEvent(event: unknown): void;
+    dispose(): void;
+}
+export interface ChildControlOptions {
+    /** The parent's bridge socket. */
+    readonly endpoint: string;
+    readonly identity: ChildIdentity;
+    /**
+     * False while this process is serving a session the parent did not launch. A bridge belongs to
+     * one child, so whatever session the process serves next must neither forward its events nor
+     * count as that child's input.
+     */
+    readonly isActive?: () => boolean;
+    readonly diagnose?: (message: string) => void;
+}
+/** The source of a Pi input event, when it is one the parent is allowed to hear about. */
+export declare function childInputSource(event: unknown): ChildInputSource | undefined;
+/** Reads the `{ message }` payload both prompt-shaped operations use. */
+export declare function promptMessage(payload: unknown): string;
+/**
+ * Answers a parent request with this child's Pi state. Idleness is the child's own answer: the
+ * parent never infers it from how long ago it last heard something.
+ */
+export declare function childState(ctx: ExtensionContext): Record<string, unknown>;
+/**
+ * Truncates bulky data (like huge file reads, grep blocks, or base64 images) in advisory events
+ * before they are serialized and pushed over the bridge. The parent projector only requires
+ * turn-level signals, not multi-megabyte payloads.
+ */
+export declare function sanitizeEventForBridge(event: unknown): unknown;
+/**
+ * Registers the bridge connection and the Pi primitives behind it. The connection keeps dialing
+ * while the parent is away, so a panel child survives a parent restart without losing its reports.
+ */
+export declare function registerChildControl(pi: ExtensionAPI, options: ChildControlOptions): ChildControl;

package/dist/child-control.js

@@ -0,0 +1,176 @@
+import { errorMessage, isRecord } from "@hheei/pi-ext-core";
+import { ChildBridgeClient } from "./bridge-client.js";
+import { BridgeError } from "./protocol.js";
+import { FORWARDED_PI_EVENT_TYPES, shouldForwardPiEvent } from "./rpc-events.js";
+const CHILD_INPUT_SOURCES = ["interactive", "extension", "rpc"];
+/** The source of a Pi input event, when it is one the parent is allowed to hear about. */
+export function childInputSource(event) {
+    if (!isRecord(event) || typeof event.source !== "string")
+        return undefined;
+    return CHILD_INPUT_SOURCES.includes(event.source)
+        ? event.source
+        : undefined;
+}
+/** Reads the `{ message }` payload both prompt-shaped operations use. */
+export function promptMessage(payload) {
+    if (!isRecord(payload) || typeof payload.message !== "string" || payload.message.trim() === "") {
+        throw new BridgeError("invalid_payload", "A prompt request requires a non-empty message");
+    }
+    return payload.message;
+}
+/**
+ * Answers a parent request with this child's Pi state. Idleness is the child's own answer: the
+ * parent never infers it from how long ago it last heard something.
+ */
+export function childState(ctx) {
+    const sessionPath = ctx.sessionManager.getSessionFile();
+    return {
+        idle: ctx.isIdle(),
+        pendingMessages: ctx.hasPendingMessages(),
+        sessionId: ctx.sessionManager.getSessionId(),
+        ...(sessionPath ? { sessionPath } : {}),
+    };
+}
+/**
+ * Truncates bulky data (like huge file reads, grep blocks, or base64 images) in advisory events
+ * before they are serialized and pushed over the bridge. The parent projector only requires
+ * turn-level signals, not multi-megabyte payloads.
+ */
+export function sanitizeEventForBridge(event) {
+    if (!isRecord(event))
+        return event;
+    if (event.type === "tool_execution_end" && isRecord(event.result)) {
+        const result = event.result;
+        if (Array.isArray(result.content)) {
+            const sanitizedContent = result.content.map((part) => {
+                if (isRecord(part) &&
+                    part.type === "text" &&
+                    typeof part.text === "string" &&
+                    part.text.length > 2000) {
+                    return {
+                        ...part,
+                        text: `${part.text.slice(0, 1000)}\n... [truncated for bridge event]`,
+                    };
+                }
+                if (isRecord(part) && part.type === "image") {
+                    return {
+                        type: "image",
+                        mimeType: part.mimeType,
+                        data: "[image omitted for bridge event]",
+                    };
+                }
+                return part;
+            });
+            return { ...event, result: { ...result, content: sanitizedContent } };
+        }
+    }
+    return event;
+}
+/**
+ * Registers the bridge connection and the Pi primitives behind it. The connection keeps dialing
+ * while the parent is away, so a panel child survives a parent restart without losing its reports.
+ */
+export function registerChildControl(pi, options) {
+    const isActive = options.isActive ?? (() => true);
+    let ctx;
+    const requireContext = () => {
+        if (ctx === undefined) {
+            throw new BridgeError("session_not_ready", "This child has no active Pi session yet");
+        }
+        return ctx;
+    };
+    const deliverPrompt = (payload, deliverAs) => {
+        const message = promptMessage(payload);
+        // A message needs a session to land in: while the process is between sessions the parent
+        // hears that instead of a silent drop.
+        requireContext();
+        if (deliverAs !== undefined)
+            pi.sendUserMessage(message, { deliverAs });
+        else
+            pi.sendUserMessage(message);
+        return { accepted: true };
+    };
+    const handleRequest = async (request) => {
+        if (!isActive()) {
+            // The process serves another session now, so it is not this child's runtime: answering
+            // would drive a session the parent never launched.
+            throw new BridgeError("inactive_session", "This process no longer serves the delegated session");
+        }
+        switch (request.operation) {
+            case "prompt":
+                return deliverPrompt(request.payload, undefined);
+            case "steer":
+                return deliverPrompt(request.payload, "steer");
+            case "follow_up":
+                return deliverPrompt(request.payload, "followUp");
+            case "get_state":
+                return childState(requireContext());
+            case "get_entries":
+                return { entries: requireContext().sessionManager.getEntries() };
+            case "abort":
+                requireContext().abort();
+                return { accepted: true };
+            case "shutdown":
+                requireContext().shutdown();
+                return { accepted: true };
+            default:
+                throw new BridgeError("unsupported_operation", `This child does not implement ${request.operation}`);
+        }
+    };
+    const client = new ChildBridgeClient({
+        endpoint: options.endpoint,
+        identity: options.identity,
+        handleRequest,
+        ...(options.diagnose === undefined ? {} : { diagnose: options.diagnose }),
+    });
+    const dispose = [];
+    // `pi.on` is declared as literal-name overloads, so a loop over the forwarded event types cannot
+    // be typed through them; every name in FORWARDED_PI_EVENT_TYPES is a real Pi event.
+    const onPiEvent = pi.on;
+    for (const type of FORWARDED_PI_EVENT_TYPES) {
+        dispose.push(onPiEvent(type, (event) => {
+            if (!isActive())
+                return;
+            if (shouldForwardPiEvent(event))
+                client.sendEvent(sanitizeEventForBridge(event));
+        }));
+    }
+    dispose.push(pi.on("input", (event) => {
+        if (!isActive())
+            return;
+        const source = childInputSource(event);
+        if (source !== undefined)
+            client.sendChildInput(source);
+    }));
+    dispose.push(pi.on("session_start", (_event, context) => {
+        ctx = context;
+    }));
+    dispose.push(pi.on("session_shutdown", () => {
+        ctx = undefined;
+    }));
+    let started = false;
+    return {
+        start(context) {
+            if (context !== undefined)
+                ctx = context;
+            if (started)
+                return;
+            started = true;
+            client.start();
+        },
+        report: (operation, payload, signal) => client.sendReport(operation, payload, signal),
+        sendEvent: (event) => client.sendEvent(event),
+        dispose: () => {
+            for (const off of dispose) {
+                try {
+                    off();
+                }
+                catch (error) {
+                    options.diagnose?.(`could not remove a bridge listener: ${errorMessage(error)}`);
+                }
+            }
+            started = false;
+            client.close();
+        },
+    };
+}

package/dist/child-process.d.ts

@@ -0,0 +1,21 @@
+export declare const DEFAULT_TERMINATE_GRACE_MS = 2000;
+export interface ChildProcessOptions {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly diagnose?: (message: string) => void;
+}
+export interface ChildRuntime {
+    readonly pid: number | undefined;
+    readonly alive: boolean;
+    /** Resolves when the process is gone; a signal death reports a null code. */
+    readonly exited: Promise<number | null>;
+    /** SIGTERM, then SIGKILL after the grace window. Idempotent. */
+    terminate(graceMs?: number): Promise<void>;
+}
+/**
+ * Starts a detached-from-the-terminal child Pi. The caller keeps the handle: this package has no
+ * supervisor process, so nothing else can end a background child after its parent is gone.
+ */
+export declare function spawnChildRuntime(options: ChildProcessOptions): ChildRuntime;