@hheei/pi-subagents 0.1.2

package/dist/child-bridge.js

@@ -0,0 +1,214 @@
+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 { 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];
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+export function shouldLeaveBoundSession(params) {
+    if (params.currentSessionId === params.boundSessionId)
+        return false;
+    return params.reason === "new" || params.reason === "resume" || params.reason === "fork";
+}
+export function isConfirmedUserInterrupt(messages) {
+    if (messages === undefined)
+        return false;
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message?.role !== "assistant")
+            continue;
+        return message.stopReason === USER_INTERRUPT_STOP_REASON;
+    }
+    return false;
+}
+export function lastActivityText(messages) {
+    if (messages === undefined)
+        return "";
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        const text = messageText(message?.content);
+        if (text !== "")
+            return text;
+    }
+    return "";
+}
+function messageText(content) {
+    if (typeof content === "string")
+        return content.trim();
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => {
+        const value = isRecord(part) ? part : undefined;
+        return value?.type === "text" && typeof value.text === "string" ? value.text : "";
+    })
+        .join("")
+        .trim();
+}
+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. */
+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);
+    registerChildTools(pi, identity, {
+        onReport: () => nudge.markReported(),
+        isBound: (sessionId) => state.bound && (state.boundSessionId === "" || sessionId === state.boundSessionId),
+    });
+    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 leave = (sessionId) => {
+        if (!state.bound)
+            return;
+        state.bound = false;
+        gate.cancel();
+        pauseSocket.close();
+        disposeWidget();
+        nudge.dispose();
+        reportLifecycle(identity, "left_session", sessionId);
+    };
+    pi.on("session_start", (event, ctx) => {
+        const sessionId = currentSessionId(ctx);
+        if (!state.bound && state.boundSessionId === "") {
+            state.boundSessionId = sessionId;
+            state.bound = true;
+            showIdentity(ctx);
+            return;
+        }
+        if (shouldLeaveBoundSession({
+            boundSessionId: state.boundSessionId,
+            currentSessionId: sessionId,
+            reason: event.reason,
+        })) {
+            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);
+        }
+        disposeWidget();
+        if (event.reason === "quit" ||
+            event.reason === "new" ||
+            event.reason === "resume" ||
+            event.reason === "fork") {
+            nudge.dispose();
+        }
+        if (event.reason === "quit") {
+            gate.cancel();
+            pauseSocket.close();
+            stop.abort();
+        }
+    });
+    pi.on("agent_end", (event, ctx) => {
+        if (!state.bound || currentSessionId(ctx) !== state.boundSessionId)
+            return;
+        const messages = Array.isArray(event.messages) ? event.messages : undefined;
+        if (!isConfirmedUserInterrupt(messages))
+            return;
+        const activity = lastActivityText(messages);
+        reportLifecycle(identity, "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-nudge.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Child-side completion reminder.
+ *
+ * Adapted from HazAT/maplezzk pi-interactive-subagents `subagent-done.ts`
+ * (MIT, upstream 7a5c96be138158a5cf6413ac819509eff12b1ccd). This version
+ * reminds the child to call `contact_parent` and never exits the session.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** Return true only when the latest assistant message ended by the model stopping normally. */
+export declare function shouldScheduleAgentEndNudge(messages: readonly {
+    role?: string;
+    stopReason?: string;
+}[] | undefined): boolean;
+export interface ChildNudgeController {
+    markReported(): void;
+    listen(pi: ExtensionAPI): void;
+    dispose(): void;
+}
+/** Owns the delay timer and the “already reported / user took over” gates. */
+export declare function createChildNudgeController(options?: {
+    readonly delayMs?: number;
+    readonly disabled?: boolean;
+}): ChildNudgeController;
+export declare function registerChildNudge(pi: ExtensionAPI): ChildNudgeController;

package/dist/child-nudge.js

@@ -0,0 +1,102 @@
+import { isRecord } from "./domain.js";
+const ASSISTANT_ROLE = "assistant";
+const NORMAL_STOP_REASON = "stop";
+const DEFAULT_NUDGE_DELAY_MS = 5_000;
+const MIN_NUDGE_DELAY_MS = 1_000;
+const NUDGE_TEXT = "You finished a turn without calling contact_parent. If the parent needs a progress update, important finding, decision, or blocker, call contact_parent now. Do not wait for the parent to poll you.";
+/** Return true only when the latest assistant message ended by the model stopping normally. */
+export function shouldScheduleAgentEndNudge(messages) {
+    if (messages === undefined || messages.length === 0)
+        return false;
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message?.role !== ASSISTANT_ROLE)
+            continue;
+        return message.stopReason === NORMAL_STOP_REASON;
+    }
+    return false;
+}
+function parseNudgeDelayMs(rawValue) {
+    const parsed = Number.parseInt(rawValue ?? "", 10);
+    if (!Number.isFinite(parsed))
+        return DEFAULT_NUDGE_DELAY_MS;
+    return Math.max(MIN_NUDGE_DELAY_MS, parsed);
+}
+function agentEndMessages(event) {
+    if (!isRecord(event) || !Array.isArray(event.messages))
+        return undefined;
+    const messages = [];
+    for (const item of event.messages) {
+        if (!isRecord(item))
+            continue;
+        messages.push({
+            ...(typeof item.role === "string" ? { role: item.role } : {}),
+            ...(typeof item.stopReason === "string" ? { stopReason: item.stopReason } : {}),
+        });
+    }
+    return messages;
+}
+/** Owns the delay timer and the “already reported / user took over” gates. */
+export function createChildNudgeController(options = {}) {
+    const delayMs = options.delayMs ?? parseNudgeDelayMs(process.env.PI_SUBAGENTS_NUDGE_DELAY_MS);
+    const disabled = options.disabled ?? process.env.PI_SUBAGENTS_NUDGE_DISABLE === "1";
+    let reported = false;
+    let userInputAfterAgentEnd = false;
+    let agentStarted = false;
+    let userTookOver = false;
+    let timer = null;
+    const clearTimer = () => {
+        if (timer === null)
+            return;
+        clearTimeout(timer);
+        timer = null;
+    };
+    return {
+        markReported() {
+            reported = true;
+            clearTimer();
+        },
+        listen(pi) {
+            pi.on("input", () => {
+                userInputAfterAgentEnd = true;
+                clearTimer();
+                if (agentStarted)
+                    userTookOver = true;
+            });
+            pi.on("before_agent_start", () => {
+                clearTimer();
+            });
+            pi.on("agent_start", () => {
+                agentStarted = true;
+                reported = false;
+                userInputAfterAgentEnd = false;
+                clearTimer();
+            });
+            pi.on("agent_end", (event) => {
+                if (disabled || reported || userTookOver) {
+                    clearTimer();
+                    return;
+                }
+                if (!shouldScheduleAgentEndNudge(agentEndMessages(event))) {
+                    clearTimer();
+                    return;
+                }
+                clearTimer();
+                timer = setTimeout(() => {
+                    timer = null;
+                    if (reported || userInputAfterAgentEnd || userTookOver)
+                        return;
+                    pi.sendUserMessage(NUDGE_TEXT, { deliverAs: "followUp" });
+                }, delayMs);
+            });
+        },
+        dispose() {
+            clearTimer();
+        },
+    };
+}
+export function registerChildNudge(pi) {
+    const controller = createChildNudgeController();
+    controller.listen(pi);
+    return controller;
+}

package/dist/commands.d.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { PublicSubagent } from "./domain.js";
+import type { SubagentManager } from "./manager.js";
+export declare function formatStatusLine(children: readonly PublicSubagent[]): string | undefined;
+export declare function registerParentCommands(pi: ExtensionAPI, manager: SubagentManager): void;
+export declare function bindParentStatus(_pi: ExtensionAPI, context: ExtensionContext, manager: SubagentManager): () => void;

package/dist/commands.js

@@ -0,0 +1,155 @@
+const STATUS_KEY = "pi-subagents";
+export function formatStatusLine(children) {
+    const visible = children.filter((child) => child.state !== "done" && child.state !== "stopped");
+    if (visible.length === 0)
+        return undefined;
+    return visible
+        .map((child) => {
+        const name = child.displayName ?? child.agent;
+        const mode = child.mode === "tui" ? "tui" : child.state;
+        const flag = child.interrupted !== undefined ? " interrupted" : "";
+        return `${name} ${mode}${flag}`;
+    })
+        .join(" · ");
+}
+function notifyResult(ctx, result, ok) {
+    if ("reason" in result && typeof result.reason === "string") {
+        ctx.ui.notify(result.reason, "error");
+        return;
+    }
+    ctx.ui.notify(ok);
+}
+function childLabel(child) {
+    const name = child.displayName ?? child.agent;
+    return `${name} ${child.id} ${child.state}/${child.mode}`;
+}
+async function pickChild(ctx, children, title) {
+    if (children.length === 0) {
+        ctx.ui.notify("No matching subagents", "warning");
+        return undefined;
+    }
+    if (children.length === 1)
+        return children[0];
+    const labels = children.map(childLabel);
+    const selected = await ctx.ui.select(title, labels);
+    if (selected === undefined)
+        return undefined;
+    return children[labels.indexOf(selected)];
+}
+async function attachSelected(ctx, manager, id) {
+    if (id !== undefined && id !== "") {
+        notifyResult(ctx, await manager.attach(id), `Attached ${id}`);
+        return;
+    }
+    const idle = (await manager.list()).filter((child) => child.mode === "rpc" && child.state === "idle");
+    const child = await pickChild(ctx, idle, "Attach idle subagent");
+    if (child === undefined)
+        return;
+    notifyResult(ctx, await manager.attach(child.id), `Attached ${child.id}`);
+}
+async function stopSelected(ctx, manager, id) {
+    if (id !== undefined && id !== "") {
+        notifyResult(ctx, await manager.stop(id), `Stopped ${id}`);
+        return;
+    }
+    const live = (await manager.list()).filter((child) => child.state !== "done" && child.state !== "stopped");
+    const child = await pickChild(ctx, live, "Stop subagent");
+    if (child === undefined)
+        return;
+    notifyResult(ctx, await manager.stop(child.id), `Stopped ${child.id}`);
+}
+export function registerParentCommands(pi, manager) {
+    pi.registerCommand("subagents", {
+        description: "List, inspect, attach, send to, or stop an owned subagent",
+        handler: async (args, ctx) => {
+            if (ctx.mode !== "tui") {
+                ctx.ui.notify("Use spawn_subagent / send_subagent / get_subagent / stop_subagent in this mode");
+                return;
+            }
+            const action = args.trim() ||
+                (await ctx.ui.select("Subagents", ["list", "inspect", "attach", "send", "stop"]));
+            if (action === undefined)
+                return;
+            const children = await manager.list();
+            if (action === "list") {
+                if (children.length === 0) {
+                    ctx.ui.notify("No subagents", "warning");
+                    return;
+                }
+                ctx.ui.notify(children.map(childLabel).join("\n"));
+                return;
+            }
+            if (action === "inspect") {
+                const child = await pickChild(ctx, children, "Inspect subagent");
+                if (child === undefined)
+                    return;
+                const inspected = await manager.get(child.id);
+                if ("reason" in inspected) {
+                    ctx.ui.notify(inspected.reason, "error");
+                    return;
+                }
+                ctx.ui.notify(`${childLabel(inspected)}\n${inspected.summary ?? "no summary"}\nmodel ${inspected.model.provider}/${inspected.model.id}`);
+                return;
+            }
+            if (action === "attach") {
+                await attachSelected(ctx, manager);
+                return;
+            }
+            if (action === "stop") {
+                await stopSelected(ctx, manager);
+                return;
+            }
+            if (action === "send") {
+                const live = children.filter((child) => child.mode === "rpc" && (child.state === "idle" || child.state === "running"));
+                const child = await pickChild(ctx, live, "Send to subagent");
+                if (child === undefined)
+                    return;
+                const message = await ctx.ui.input("Message for subagent");
+                if (message === undefined || message.trim() === "")
+                    return;
+                notifyResult(ctx, await manager.send(child.id, message.trim()), `Sent to ${child.id}`);
+            }
+        },
+    });
+    pi.registerCommand("attach-subagent", {
+        description: "Open an RPC child as a native Pi TUI. Idle children switch immediately; busy children wait for the current turn to finish. The session must already be flushed.",
+        handler: async (args, ctx) => {
+            await attachSelected(ctx, manager, args.trim());
+        },
+    });
+    pi.registerCommand("stop-subagent", {
+        description: "Stop an owned subagent",
+        handler: async (args, ctx) => {
+            await stopSelected(ctx, manager, args.trim());
+        },
+    });
+    pi.registerShortcut("ctrl+shift+a", {
+        description: "Attach idle subagent",
+        handler: (ctx) => {
+            if (ctx.mode !== "tui")
+                return;
+            return attachSelected(ctx, manager);
+        },
+    });
+    pi.registerShortcut("ctrl+shift+s", {
+        description: "Stop subagent",
+        handler: (ctx) => {
+            if (ctx.mode !== "tui")
+                return;
+            return stopSelected(ctx, manager);
+        },
+    });
+}
+export function bindParentStatus(_pi, context, manager) {
+    const refresh = () => {
+        void manager.list().then((children) => {
+            context.ui.setStatus(STATUS_KEY, formatStatusLine(children));
+        });
+    };
+    const unsubscribe = manager.onChange(refresh);
+    refresh();
+    return () => {
+        unsubscribe();
+        context.ui.setStatus(STATUS_KEY, undefined);
+    };
+}

package/dist/connector.d.ts

@@ -0,0 +1,53 @@
+import { type ChildIdentity } from "./domain.js";
+import { type RunnerOperation } from "./protocol.js";
+export interface RunnerConnectionOptions {
+    /** Unix socket path published by the runner. */
+    readonly endpoint: string;
+    readonly identity: ChildIdentity;
+    readonly token: string;
+    readonly maxFrameBytes?: number;
+    readonly maxPendingRequests?: number;
+    readonly requestTimeoutMs?: number;
+    readonly connectTimeoutMs?: number;
+    readonly role?: "controller" | "reporter" | "recovery" | "bridge";
+    readonly claimId?: string;
+}
+/**
+ * Parent-side client of the runner IPC endpoint.
+ *
+ * The connection is re-connectable by design: `close()` only releases this
+ * parent's local socket and in-flight requests. It never terminates the runner
+ * or the Pi child that the runner owns.
+ */
+export declare class RunnerConnection {
+    #private;
+    constructor(options: RunnerConnectionOptions);
+    connect(signal?: AbortSignal): Promise<void>;
+    get connected(): boolean;
+    request(operation: RunnerOperation, payload?: unknown, options?: {
+        readonly signal?: AbortSignal;
+        readonly timeoutMs?: number;
+    }): Promise<unknown>;
+    onEvent(listener: (event: unknown) => void): () => void;
+    /**
+     * Releases the local socket, reader, listeners and in-flight requests. The
+     * runner keeps running and can be reconnected from the same identity.
+     */
+    close(): void;
+}
+/** Sends one child report through a short-lived authenticated reporter connection. */
+export declare function sendReportToRunner(identity: ChildIdentity, report: unknown, signal?: AbortSignal): Promise<void>;
+/** Sends one child lifecycle event through a short-lived authenticated reporter connection. */
+export declare function sendLifecycleToRunner(identity: ChildIdentity, payload: unknown, signal?: AbortSignal): Promise<void>;
+/**
+ * Connects to a runner endpoint that may still be starting up.
+ *
+ * Readiness is never a fixed sleep: each attempt is a real connect plus
+ * identity handshake, so a resolved promise means the runner accepted this
+ * controller. Only connection-level failures inside the deadline are retried.
+ */
+export declare function connectWithRetry(connection: Pick<RunnerConnection, "connect">, options?: {
+    readonly attempts?: number;
+    readonly delayMs?: number;
+    readonly signal?: AbortSignal;
+}): Promise<void>;