@evandu/super-pi 0.0.0-stage → 0.1.1

package/dist/server/subagents.js

@@ -0,0 +1,542 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdir, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { agentSpawnArgs, readAgents } from "./agents.js";
+import { resolvePiCommand, shellQuote } from "./pi-command.js";
+import { buildExtensionUiResponse, describeExtensionUiRequest, killTree, RpcChannel, } from "./runtime.js";
+import { describeToolCall, TOOL_DETAIL_CAP } from "./tool-calls.js";
+/**
+ * The tool-call derivation now lives in `tool-calls.js`, because the primary agent's runtime needs the
+ * identical mapping and `subagents.ts` already imports `runtime.ts` - so the shared definition has to sit
+ * below both of them.
+ *
+ * RE-EXPORTED rather than moved silently. `scripts/agent-vis-records.test.mjs` imports both of these from
+ * this module, and a card that quietly lost its only derivation would still typecheck. Keeping the names
+ * exported here means that test keeps pointing at the one definition that also serves a call block.
+ */
+export { describeToolCall, TOOL_DETAIL_CAP };
+/**
+ * Spawning and draining ONE child Pi, per [docs/SUBAGENT-DESIGN.md](../docs/SUBAGENT-DESIGN.md) §4.
+ * No records, no events, no store: this file's whole job is that a `mode: subagent` definition becomes a
+ * real OS process whose text comes back as a stream and a final answer. What the browser does with that
+ * is a later step, and keeping it out is why `run()` returns a value instead of emitting one.
+ *
+ * The mechanism is the primary agent's, reused rather than reinvented: the same `readAgents` /
+ * `agentSpawnArgs`, the same `resolvePiCommand` / `shellQuote` resolution, the same `RpcChannel` and
+ * JSONL drain loop, the same `killTree`. A sub-agent is the same thing one layer down.
+ */
+/** How long the drain loop waits for a record before re-checking the child and the caller's signal. */
+const DRAIN_POLL_MS = 100;
+/**
+ * The run id every dispatch gets unless a caller supplies one: `sub_<uuid>`, and Pi's `--session-id`
+ * alongside it. Exported so a caller that must know the id BEFORE the spawn - the recorder, which has to
+ * write a `running` row before the child exists - generates exactly the id this would have generated.
+ */
+export const newSubagentRunId = () => `sub_${randomUUID()}`;
+/** Token/cost usage for a run that produced no finished message. */
+const NO_USAGE = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+/**
+ * Pi's session records that ARE part of one turn's lifecycle, so this supervisor has nothing to do with
+ * them, and so announcing them once per distinct type and then tallying the rest turns an ordinary run
+ * into a thousand warnings.
+ *
+ * THE CRITERION IS "WE KNOW EXACTLY WHAT THIS IS", not "it is noisy" and not "we are bored of it". Each
+ * name below is a member of Pi's own published `AgentSessionEvent` union, and every one of them arrives on
+ * every single run: `session.subscribe((event) => output(toJsonEvent(event)))` forwards the union
+ * unfiltered (modes/rpc/rpc-mode.ts:355-356), so a host that acts on a handful of them and treats the rest
+ * as silence is the only possible design here. Membership is therefore a CLAIM about Pi's protocol, and
+ * `scripts/subagent-noise.test.mjs` is what keeps the claim honest in both directions: a fake Pi emitting
+ * this whole set must produce no warning, and a fake Pi emitting a type that is NOT in it must still
+ * produce one. That second half is the point - the day Pi adds a record here, it lands in the tally
+ * instead of vanishing (the failure mode R2 §4.3/P1-1 records: a record dropped silently makes a protocol
+ * change look like it worked).
+ *
+ * What is deliberately NOT in this set, even though Pi documents all of it: `queue_update`,
+ * `compaction_start` / `compaction_end`, `auto_retry_start` / `auto_retry_end`, `summarization_retry_*`,
+ * `bash_execution_update`, `session_info_changed`, `thinking_level_changed`. Those are known too, but
+ * this supervisor has no answer for them - a compacted or retried run is a run whose answer a caller
+ * should distrust, and R2 P1-1 names `queue_update` as exactly the record a future feature must consume
+ * rather than have quietly swallowed. "We know what it is" is the necessary condition for exemption here;
+ * it is not sufficient, and these keep announcing until something actually handles them.
+ */
+const KNOWN_LIFECYCLE_RECORDS = new Set([
+    // Pi's own framing of a run, one pair per child (packages/agent/src/types.ts:518-519). The bookends
+    // carry no information this supervisor can use, and `agent_end` carries every message in the transcript,
+    // which by contract Super Pi never reads - see `run()`'s "Pi owns the directory".
+    "agent_start",
+    "agent_end",
+    // The turn and message boundaries AROUND the records this loop does act on. `turn_end` is where Pi
+    // finishes a turn and `message_start` / `message_end` bracket every message; the loop needs none of
+    // them because it tracks the assistant message through the inner `start` / `done` events instead
+    // (modes/json-event.ts:40-44 says the same: "message_start provides the initial message, deltas build
+    // it, and message_end provides the final authoritative message").
+    "turn_start",
+    "turn_end",
+    "message_start",
+    "message_end",
+    // The rest of ONE tool call's lifecycle. `tool_execution_start` is handled and reported as the tool
+    // line; these two are the same call's progress and result, carrying `partialResult` / `result` payloads
+    // that `SubagentToolCall` deliberately drops because they can be large and can hold file contents. One
+    // line per call is the whole contract, so two more records per call is pure repetition.
+    "tool_execution_update",
+    "tool_execution_end",
+    // Pi telling us it appended an entry to the transcript it owns. Same contract as `agent_end`: Super Pi
+    // never reads Pi's transcript, so there is nothing to do with an entry-level receipt.
+    "entry_appended",
+]);
+/**
+ * The inner events of a `message_update` that are part of an assistant message's construction, for the
+ * same reason and under the same criterion as `KNOWN_LIFECYCLE_RECORDS` - every name is a member of Pi's
+ * published `AssistantMessageEvent` union (packages/ai/src/types.ts:788-804) minus `partial`, and each one
+ * fires on every run. The union's members the loop DOES consume are `start`, `text_delta`, `done` and
+ * `error`; these are the rest.
+ */
+const KNOWN_LIFECYCLE_EVENTS = new Set([
+    // The boundaries of the very `text_delta` stream this loop accumulates. Real Pi emits a `text_start` /
+    // `text_end` pair around EVERY text block, so a run with one paragraph per turn emits two of these per
+    // turn for output the loop already has.
+    "text_start",
+    "text_end",
+    // The model's reasoning stream, as a whole lifecycle rather than just its `thinking_delta` - one real
+    // run logged 1449 of them, which is one per token of thought. Nothing here is a bug or a protocol
+    // surprise; this supervisor's contract is `finalText`, not the model's private thinking.
+    // ROADMAP NOTE: if thinking ever becomes part of a sub-agent card, this is where it is plumbed in -
+    // accumulate the deltas and render them - and THAT change should move these three out of this set
+    // deliberately, at the same time as it teaches the UI to show them. Until then they are known and
+    // deliberately unused, which is different from unknown.
+    "thinking_start",
+    "thinking_delta",
+    "thinking_end",
+    // A tool call being assembled inside the message. The tool LINE this supervisor reports comes from the
+    // outer `tool_execution_start`, which carries the authoritative `toolCallId` and `toolName`; these three
+    // are the incremental JSON of arguments the loop deliberately does not keep.
+    "toolcall_start",
+    "toolcall_delta",
+    "toolcall_end",
+]);
+/**
+ * A run that ended because the caller aborted it.
+ *
+ * A named error rather than a message a caller has to pattern-match, because "the user pressed stop" and
+ * "the child failed" are different outcomes for whoever reports this run later, and collapsing them into
+ * one rejected promise would force that decision back out of string matching.
+ */
+export class SubagentCancelled extends Error {
+    runId;
+    constructor(runId) {
+        super(`sub-agent run ${runId} was cancelled before it settled`);
+        this.runId = runId;
+        this.name = "SubagentCancelled";
+    }
+}
+/**
+ * The text of one assistant message: its FIRST text block, exactly as the reference implementation reads
+ * it (examples/extensions/subagent/index.ts:170-180). A message whose only content is a tool call has no
+ * text, so "" is a real answer here rather than a failure.
+ */
+const textOf = (part) => part !== null && typeof part === "object" && part.type === "text" && typeof part.text === "string"
+    ? part.text
+    : undefined;
+const assistantText = (message) => {
+    const content = message?.content;
+    if (!Array.isArray(content))
+        return "";
+    for (const part of content) {
+        const text = textOf(part);
+        if (text !== undefined)
+            return text;
+    }
+    return "";
+};
+/**
+ * Adds one finished message's usage into the run total.
+ *
+ * Read ONLY on `done`, never on a delta: Pi repeats the same per-message usage on every update of that
+ * message (modes/json-event.ts:56), so summing per delta would count a message's tokens once per token
+ * in it. `cost` is `usage.cost.total`, the provider's own number rather than a re-derivation of it.
+ */
+const addUsage = (total, usage) => {
+    total.input += usage?.input ?? 0;
+    total.output += usage?.output ?? 0;
+    total.cacheRead += usage?.cacheRead ?? 0;
+    total.cacheWrite += usage?.cacheWrite ?? 0;
+    total.cost += usage?.cost?.total ?? 0;
+    total.turns += 1;
+};
+/** Spawns sub-agent children Pi and drains their JSONL RPC streams. */
+export class SubagentSupervisor {
+    sessionDir;
+    agents;
+    pi;
+    /** Live children by run id, so a caller can name the process it means. Cleared in the run's `finally`. */
+    children = new Map();
+    /**
+     * `command` and `agents` are the same two override points `PiRpcRuntime` takes, and for the same
+     * reasons: a test needs to launch a fake peer, and a Pi installed somewhere unusual needs to be
+     * reachable. `Pi` is resolved once, because a resolution that could change mid-run would make one
+     * child's spawn line depend on when it was started.
+     */
+    constructor(sessionDir, command, agents = { dir: join(sessionDir, "agents"), promptDir: join(sessionDir, "agent-prompts") }) {
+        this.sessionDir = sessionDir;
+        this.agents = agents;
+        this.pi = resolvePiCommand({ command });
+        if (!this.pi.found)
+            console.warn(`SubagentSupervisor: ${this.pi.reason}`);
+    }
+    /**
+     * Every child this supervisor still owns, optionally narrowed to one conversation.
+     *
+     * A live view rather than a returned handle, because the caller cannot have the id before the run:
+     * `run()` returns the RESULT, and a stop button needs the pid while the promise is still pending.
+     * Deleted as soon as the child is gone, so a caller that polls it sees the truth rather than a
+     * remembered one.
+     */
+    liveRuns(conversationId) {
+        return [...this.children].map(([id, run]) => ({ id, conversationId: run.conversationId, pid: run.child.pid }));
+    }
+    /**
+     * Runs one sub-agent to completion and returns what it said.
+     *
+     * The three spawn-time decisions, all of which the design fixes rather than leaves open:
+     *
+     * - `--mode rpc`, NOT the reference implementation's `--mode json -p`. In print mode a child that
+     *   wants to ask something has nowhere to ask and hangs; in RPC mode its questions arrive as
+     *   `extension_ui_request` records on the channel Super Pi already owns. That is the whole reason this
+     *   supervisor exists instead of shipping Pi's extension.
+     * - `--session-dir` shared by every child, `--session-id` unique per run, so Pi owns the directory and
+     *   Super Pi never has to read a transcript it could only misread.
+     * - `agentSpawnArgs` verbatim, so a sub-agent's tool allowlist and prompt go through the one proven
+     *   translation rather than a second hand-rolled one.
+     *
+     * The TASK goes over RPC stdin, never on argv. The reference passes it as a positional argument, which
+     * under `shell: true` on Windows is cmd.exe's to parse: an ampersand or a pipe in a model's own words
+     * becomes a command. `{ type: "prompt" }` is exactly how the primary agent is already prompted, so
+     * this costs nothing and removes the whole class of bug.
+     */
+    async run(input) {
+        const { conversationId, agentId, task, cwd, model, host, signal, onTextDelta, onToolCall, onToolEnd, onThinking, onStage } = input;
+        // Refused here, with the reason, rather than handed to the spawn: an ENOENT from `spawn` reads as
+        // "the app is broken" and hides the one fact that matters, which is where it looked for Pi.
+        if (!this.pi.found)
+            throw new Error(this.pi.reason);
+        if (!task.trim())
+            throw new Error(`sub-agent ${JSON.stringify(agentId)} was dispatched with an empty task`);
+        // The caller's id, or the one this would have made. Refused rather than sanitised: a mangled id
+        // would still spawn, still write a Pi transcript, and still be unreconcilable at the next startup.
+        const supplied = input.id;
+        if (supplied !== undefined && !/^sub_[A-Za-z0-9_-]{1,120}$/.test(supplied))
+            throw new Error(`A caller-supplied sub-agent run id must look like ${newSubagentRunId()}; got ${JSON.stringify(supplied)}.`);
+        const id = supplied ?? newSubagentRunId();
+        // Normalized first, and required to be a real directory: a deleted workspace is a visible failure,
+        // never a reason to run the child somewhere else.
+        const childCwd = resolve(cwd);
+        const info = await stat(childCwd).catch(() => undefined);
+        if (!info?.isDirectory())
+            throw new Error(`Workspace directory for conversation ${conversationId} does not exist or is not a directory: ${childCwd}. Refusing to run sub-agent ${JSON.stringify(agentId)} in any other directory.`);
+        // Fetched before the spawn, so a bad definition fails the run loudly instead of starting a Pi that
+        // silently ignores it - and so a PRIMARY agent cannot be dispatched as a sub-agent by accident.
+        const agent = await this.subagentDefinition(agentId);
+        // The child's own `tools:` map, minus whatever the dispatching agent denied. Never the parent's
+        // ALLOWLIST - see `SubagentRunInput.denyTools` for why that asymmetry is the reference's too.
+        const agentArgs = await agentSpawnArgs(this.agents.promptDir, agent, { denyTools: input.denyTools ?? [] });
+        const sessionDirectory = join(this.sessionDir, "subagents");
+        await mkdir(sessionDirectory, { recursive: true });
+        const args = ["--mode", "rpc", "--session-dir", sessionDirectory, "--session-id", id, ...agentArgs];
+        // Model inheritance: the definition wins, otherwise the parent's current model, otherwise Pi's own
+        // default. "Omit the model and get what the parent is running on" is the default worth having, and it
+        // is a spawn-time flag because there is no RPC command to change it later.
+        const chosen = agent.model ?? (model?.provider && model.modelId ? { provider: model.provider, modelId: model.modelId } : undefined);
+        if (chosen)
+            args.push("--provider", chosen.provider, "--model", chosen.modelId);
+        if (agent.thinkingLevel)
+            args.push("--thinking", agent.thinkingLevel);
+        // npm exposes global CLIs as .cmd shims on Windows; Node requires a shell to launch those shims.
+        const child = spawn(shellQuote(this.pi.command), args, { cwd: childCwd, stdio: ["pipe", "pipe", "pipe"], shell: process.platform === "win32" });
+        this.children.set(id, { conversationId, child });
+        const channel = new RpcChannel(child);
+        // Pi is asked to stop first and killed only if that is not enough, so a child that can unwind its own
+        // tools gets to. `channel.write` is deliberately not used: it throws on a closed pipe, and an abort
+        // handler that throws inside a listener would surface as an unhandled rejection instead of a cancel.
+        const abort = () => {
+            if (child.exitCode === null && !child.stdin.destroyed)
+                child.stdin.write(`${JSON.stringify({ id: "abort", type: "abort" })}\n`);
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+        /** Every delta of the run, for a child that streams text but never sends a `done`. */
+        let streamed = "";
+        /** The current assistant message's text, reset by `start` and replaced by `done`. */
+        let current = "";
+        /** The last assistant message's text, which is the run's output. */
+        let finalText = "";
+        const usage = { ...NO_USAGE };
+        /** Set rather than thrown so a child's own failure is reported AFTER its output has been drained. */
+        let failed;
+        /**
+         * Which phase the child is in, for a caller that has to say where a run died.
+         *
+         * Changed ONLY at a record the drain loop actually consumed, so `onStage` cannot report a phase that
+         * never happened - which is what keeps a failure card's 「卡在哪」 an observation rather than a guess.
+         * Starts at `dispatch`, which covers every refusal above the spawn: an unknown agent, a deleted
+         * workspace, a Pi that is not installed. Those throw before a child exists, and "it never got as
+         * far as being asked anything" is the accurate thing to say about all of them.
+         */
+        let stage = "dispatch";
+        const enter = (next) => {
+            if (stage === next)
+                return;
+            stage = next;
+            onStage?.(next);
+        };
+        try {
+            channel.write({ id: "prompt", type: "prompt", message: task });
+            enter("prompt");
+            let settled = false;
+            // Nothing may be dropped without a trace. Pi emits a wide, open-ended family of session events, so
+            // an unhandled record is announced once per distinct type and then tallied instead of logged per event.
+            // "Unhandled" means "not in KNOWN_LIFECYCLE_RECORDS / KNOWN_LIFECYCLE_EVENTS and not consumed above",
+            // i.e. genuinely unrecognised - NOT merely frequent. The exemption sets are the whole reason an
+            // ordinary run is quiet while a protocol change is still loud; keep that ordering when editing them.
+            const announced = new Set();
+            const repeats = new Map();
+            const noteUnhandled = (key) => {
+                if (announced.has(key))
+                    repeats.set(key, (repeats.get(key) ?? 0) + 1);
+                else {
+                    announced.add(key);
+                    console.warn(`SubagentSupervisor: unhandled child record ${key} - consumed without action.`);
+                }
+            };
+            // A child asking a question is exactly why RPC mode was chosen, and `host` is the other half of
+            // that choice: with one, the question reaches a human and Pi stays blocked for as long as they take.
+            // The host speaks the same protocol the primary agent's does (`describeExtensionUiRequest` /
+            // `buildExtensionUiResponse` are shared with `PiRpcRuntime`), so there is exactly one definition of
+            // "what Pi's nine methods mean" in the codebase rather than one per spawner.
+            //
+            // The reply always carries the record's OWN `requestId`, never the host's key for it: the host may
+            // scope that key per run or per conversation so two questions cannot settle each other, and leaking
+            // that prefix back into the child's protocol would make Pi wait forever on an id it never issued.
+            const ui = {
+                seen: new Set(),
+                aborted: new Promise((resolve) => { if (signal?.aborted)
+                    resolve(undefined);
+                else
+                    signal?.addEventListener("abort", () => resolve(undefined), { once: true }); }),
+                exited: new Promise((resolve) => child.once("exit", () => resolve(undefined))),
+            };
+            const handleExtensionUi = async (record) => {
+                const request = describeExtensionUiRequest(record);
+                if (!request) {
+                    console.warn(`SubagentSupervisor: sub-agent ${agentId} (${id}) sent extension_ui_request method=${JSON.stringify(record.method ?? null)} id=${JSON.stringify(record.id ?? null)}, which is not one of Pi's nine Extension UI methods - consumed without reply.`);
+                    return;
+                }
+                // `channel.write` is deliberately not used for the reply, for the same reason it is not used for
+                // the abort: it throws on a closed pipe, and a throw from inside a host callback would surface as
+                // an unhandled rejection rather than as the failure it actually is.
+                const reply = (response) => { if (child.exitCode === null && !child.stdin.destroyed)
+                    child.stdin.write(`${JSON.stringify(response)}\n`); };
+                // The five one-way methods carry no question and Pi holds no pending entry for them, so a response
+                // would resolve nothing. Pushed to the host un-awaited; a host that throws is announced, not fatal.
+                if (!request.blocking) {
+                    try {
+                        host?.notify(request);
+                    }
+                    catch (error) {
+                        console.warn(`SubagentSupervisor: extension_ui notify for ${request.method} id=${request.requestId} in sub-agent ${agentId} (${id}) threw in the host: ${error instanceof Error ? error.message : "unknown error"}`);
+                    }
+                    return;
+                }
+                // Pi parks one pending entry per request id, so a duplicate id is the same question twice. Answering
+                // it twice would write two responses into one slot.
+                if (ui.seen.has(request.requestId)) {
+                    console.warn(`SubagentSupervisor: sub-agent ${agentId} (${id}) sent extension_ui_request ${request.method} id=${request.requestId} twice - second copy consumed without reply.`);
+                    return;
+                }
+                ui.seen.add(request.requestId);
+                if (!host) {
+                    // No human can be asked, so the honest reply is "cancelled". Auto-answering with options[0] or
+                    // confirmed:false would look to Pi exactly like a decision, and the user would never learn a
+                    // question was asked of them.
+                    console.warn(`SubagentSupervisor: sub-agent ${agentId} (${id}) used ${request.method} id=${request.requestId}, and this run has no UI host to answer it - cancelled rather than answering on a human's behalf.`);
+                    reply({ type: "extension_ui_response", id: request.requestId, cancelled: true });
+                    return;
+                }
+                // Raced against abort and exit, because this `await` parks the drain loop and the loop cannot see
+                // either of them on its own: a question outliving its run would leave the child blocked forever on
+                // a reply that can no longer be written.
+                const cancelled = { cancelled: true };
+                let answer;
+                try {
+                    answer = await Promise.race([host.ask(request), ui.aborted.then(() => cancelled), ui.exited.then(() => cancelled)]);
+                }
+                catch (error) {
+                    console.warn(`SubagentSupervisor: sub-agent ${agentId} (${id}) got no answer for ${request.method} id=${request.requestId} (host failed: ${error instanceof Error ? error.message : "unknown error"}) - cancelled.`);
+                    answer = cancelled;
+                }
+                reply(buildExtensionUiResponse(request, answer));
+            };
+            while (!settled) {
+                // Checked between polls rather than only on the abort event: a child that ignores `abort` must
+                // not be able to hold the run open, and the kill in `finally` is what actually ends it.
+                if (signal?.aborted)
+                    throw new SubagentCancelled(id);
+                for (;;) {
+                    const record = await channel.next(DRAIN_POLL_MS);
+                    if (!record)
+                        break;
+                    if (record.type === "response" && record.id === "prompt" && record.success === false)
+                        throw new Error(`Pi rejected the sub-agent task: ${record.error ?? "no reason given"}`);
+                    if (record.type === "message_update") {
+                        const event = record.assistantMessageEvent;
+                        // `text_delta` is the only inner event that is output. `start` and `done` are the boundaries
+                        // that make "the last assistant message" knowable at all: without them a child that produced
+                        // three messages would report all three concatenated as one answer.
+                        if (event?.type === "text_delta") {
+                            const delta = event.delta ?? "";
+                            streamed += delta;
+                            current += delta;
+                            enter("turn");
+                            onTextDelta?.(delta);
+                        }
+                        else if (event?.type === "start") {
+                            current = "";
+                            enter("turn");
+                        }
+                        else if (event?.type === "done") {
+                            // `done` carries the AUTHORITATIVE message, so its text wins over what the deltas added up
+                            // to; the accumulated text stays as the fallback for a child that streams without a `done`.
+                            current = assistantText(event.message) || current;
+                            finalText = current;
+                            addUsage(usage, record.usage);
+                            enter("turn");
+                            const reason = event.message?.stopReason ?? event.reason;
+                            if (reason === "error" || reason === "aborted")
+                                failed ??= `sub-agent ${agentId} (${id}) stopped with reason ${reason}: ${assistantText(event.message) || "no output"}`;
+                        }
+                        else if (event?.type === "error") {
+                            failed ??= `sub-agent ${agentId} (${id}) reported ${event.reason ?? "an error"}: ${assistantText(event.message) || "no detail from Pi"}`;
+                        }
+                        else if (event?.type === "thinking_delta") {
+                            // CONSUMED, not discarded. A reasoning model spends the first seconds of every turn here,
+                            // emitting no text at all, so this record is the only evidence the child is alive and
+                            // working during exactly the window a card otherwise looks frozen. See `onThinking`.
+                            enter("turn");
+                            onThinking?.();
+                            continue;
+                        }
+                        else if (KNOWN_LIFECYCLE_EVENTS.has(event?.type ?? "")) {
+                            // Known, and this supervisor has no use for it - see the set's own comment for why each name
+                            // qualifies. Deliberately NOT a blanket ignore: anything outside the set still falls through
+                            // to `noteUnhandled`, which is what catches Pi adding an event shape.
+                        }
+                        else {
+                            noteUnhandled(`message_update:${JSON.stringify(event?.type ?? "(missing)")}`);
+                        }
+                        continue;
+                    }
+                    if (record.type === "tool_execution_start") {
+                        // The `args` on this record are exactly what used to be thrown away with the record itself.
+                        // They are read, not copied: `describeToolCall` turns them into one bounded label and the
+                        // object itself goes no further. See that function for the whole argument-vs-transcript line.
+                        enter("tool");
+                        onToolCall?.({ id: record.toolCallId ?? "", name: record.toolName ?? "unknown", detail: describeToolCall(record.toolName ?? "unknown", record.args) });
+                        continue;
+                    }
+                    if (record.type === "tool_execution_end") {
+                        // THE OTHER HALF OF THE SAME CALL, and the half that makes a row mean something. Until Pi
+                        // started sending this, a `read` row could only ever say that a `read` happened: not whether
+                        // it found the file, not how long a slow call had been running, and - for a card whose child
+                        // is still working - not whether the row was even finished yet.
+                        //
+                        // ONLY `isError` AND `durationMs` CROSS OVER. `result` is deliberately not read: for a `read`
+                        // it is the file's contents, and a card row is persisted in a file that is serialized on
+                        // every single broadcast. `durationMs` is Pi's own number off a monotonic clock, so it is
+                        // the one outcome fact available for EVERY tool rather than only for result shapes this code
+                        // would have to guess at.
+                        enter("turn");
+                        onToolEnd?.({
+                            id: record.toolCallId ?? "",
+                            name: record.toolName ?? "unknown",
+                            status: record.isError === true ? "error" : "ok",
+                            ...(typeof record.durationMs === "number" && Number.isFinite(record.durationMs) ? { durationMs: Math.max(0, Math.round(record.durationMs)) } : {}),
+                        });
+                        continue;
+                    }
+                    if (record.type === "extension_ui_request") {
+                        await handleExtensionUi(record);
+                        continue;
+                    }
+                    // Pi caught this inside its own extension host, so it never becomes a thrown failure there. Every
+                    // run is a fresh process, so any extension_error seen while draining belongs to the task in
+                    // flight - and a sub-agent whose extension failed has not really done the job.
+                    if (record.type === "extension_error")
+                        throw new Error(`Pi extension error in ${record.extensionPath ?? "unknown path"} (${record.event ?? "unknown event"}): ${record.error ?? "unknown error"}`);
+                    if (record.type === "agent_settled") {
+                        enter("settle");
+                        settled = true;
+                        continue;
+                    }
+                    // Known lifecycle, no action needed - see the set's own comment. Anything NOT in the set lands on
+                    // `noteUnhandled` below, so a record type this build has never heard of is still announced.
+                    if (KNOWN_LIFECYCLE_RECORDS.has(record.type ?? ""))
+                        continue;
+                    noteUnhandled(`type ${JSON.stringify(record.type ?? "(missing type)")}`);
+                }
+                // A dead child will never settle, so waiting out another poll would only delay the failure.
+                if (!settled && child.exitCode !== null)
+                    throw new Error(`sub-agent ${agentId} (${id}) exited before settling (code ${child.exitCode}). ${channel.stderr.trim()}`);
+            }
+            for (const [key, count] of repeats)
+                console.warn(`SubagentSupervisor: ${count} further unhandled child record(s) of ${key}.`);
+            // Checked again after the loop, because the poll above can consume the very record `agent_settled`
+            // emits and the abort at the same time: a run the user stopped must not report success just because
+            // Pi happened to finish while it was being cancelled.
+            if (signal?.aborted)
+                throw new SubagentCancelled(id);
+            if (failed)
+                throw new Error(failed);
+            // No `done` at all is a child that streamed and vanished; the deltas are then the best answer there
+            // is, and returning them beats returning "" for work that demonstrably happened.
+            return { id, sessionId: id, finalText: finalText || streamed, usage };
+        }
+        finally {
+            signal?.removeEventListener("abort", abort);
+            this.children.delete(id);
+            // The run is not over until the child is actually gone: a process still tearing down still holds a
+            // lock on its working directory, so a caller that removes that directory the moment run() settles
+            // would hit EBUSY on Windows.
+            if (child.exitCode === null && child.pid !== undefined) {
+                if (!child.killed) {
+                    // The TREE, never the shim: Super Pi spawns pi.cmd through a .cmd shim with shell:true, so the
+                    // direct child is cmd.exe and the real Pi is its grandchild. Killing only the shim leaks a Pi
+                    // that keeps holding the workspace directory, which is the failure this exact call already had
+                    // to be written for on the primary agent's side.
+                    if (process.platform === "win32")
+                        await killTree(child.pid);
+                    else
+                        child.kill();
+                }
+                if (child.exitCode === null) {
+                    // The 5s backstop matches the primary agent's side (runtime.ts answer() / readCatalog()): the
+                    // kill precedes this subscription, so an exit landing in between is dropped and the promise
+                    // would never settle - hanging the sub-agent run instead of ending it.
+                    await new Promise((resolve) => { child.once("exit", resolve); setTimeout(resolve, 5000); });
+                }
+            }
+        }
+    }
+    /**
+     * The definition this run will use, or the reason there is none.
+     *
+     * Read with `mode: "subagent"`, so a primary agent is not found by id at all rather than found and
+     * then judged: a sub-agent definition is the same `agents/*.md` file with a different `mode`, and this
+     * is the filter that keeps the two rosters from ever meeting.
+     */
+    async subagentDefinition(agentId) {
+        const { agents, problems } = await readAgents(this.agents.dir, { mode: "subagent" });
+        const agent = agents.find((item) => item.id === agentId);
+        if (agent)
+            return agent;
+        throw new Error(`sub-agent ${JSON.stringify(agentId)} is not a subagent definition in ${this.agents.dir}${problems.length ? ` (${problems.length} file(s) there are not usable agents)` : ""}. A sub-agent is an agents/*.md file with \`mode: subagent\`; a primary agent is chosen by a human and is deliberately not dispatchable as one.`);
+    }
+}