@evandu/super-pi 0.0.0-stage → 0.1.1

package/dist/server/subagent-runs.d.ts

@@ -0,0 +1,142 @@
+import type { ExtensionUiHost } from "./runtime.js";
+import { type SubagentSupervisor } from "./subagents.js";
+import type { Store } from "./store.js";
+import type { ModelSelection, ServerEvent, SubagentRun } from "./types.js";
+/**
+ * Making one sub-agent run VISIBLE and RECOVERABLE, per
+ * [docs/SUBAGENT-DESIGN.md](../../docs/SUBAGENT-DESIGN.md) §5-§6.
+ *
+ * `subagents.ts` spawns and drains; this file remembers and publishes. The split is the same one Part 1
+ * drew: a spawner that also wrote records would have to be tested against a store to prove it streams,
+ * and a store that also spawned children could not be tested without one. Everything here is about the
+ * two obligations the design names and nothing else:
+ *
+ * 1. **A record before the child.** Written as `running` BEFORE `run()` is called, so a server that dies
+ *    mid-run leaves an orphan - and `Store.open` fails that orphan with a reason on the next start.
+ * 2. **A snapshot on every delta.** `subagent.event` carries the run as it stands, not just at the end,
+ *    because streaming a sub-agent is the entire reason Super Pi spawns its own instead of shipping Pi's
+ *    extension (design §2, reason 1).
+ *
+ * What deliberately does NOT go into either is the child's transcript. See `SubagentRun`.
+ */
+/**
+ * The model-visible output cap, 50 KB - design doc §6's `PER_TASK_OUTPUT_CAP`, taken from the reference
+ * implementation (`index.ts:36`) rather than invented here.
+ *
+ * APPLIED TO THE STORED COPY ONLY. A human looking at a sub-agent is debugging it, and trimming its
+ * answer to fit somebody else's context window is the wrong trade for them; the browser gets every byte
+ * through `subagent.event`, and `outputTruncated` is what tells a reader the stored copy is less than
+ * what was said. The parent model is handed the capped copy, because that is the window it actually has.
+ */
+export declare const PER_TASK_OUTPUT_CAP: number;
+/** What a caller supplies to dispatch one run. The workspace directory is required, like `AnswerInput.cwd`. */
+export type SubagentDispatch = {
+    id?: string;
+    conversationId: string;
+    agentId: string;
+    task: string;
+    /**
+     * Who decided to run this. Defaults to "human" when omitted, which is right for every caller that
+     * predates the task tool; the `/api/subagent/dispatch` endpoint - reachable only from the task tool -
+     * passes "model" explicitly.
+     */
+    dispatchedBy?: "human" | "model";
+    parentRunId?: string;
+    depth?: number;
+    loopId?: string;
+    /** Optional orchestration label. The dispatcher treats labels as opaque data. */
+    role?: string;
+    /** The dispatching conversation's workspace, resolved by the caller. Never defaulted to the server's own directory. */
+    cwd: string;
+    model?: ModelSelection;
+    /**
+     * Tools the dispatching agent denied, inherited by the child. Carried all the way down to
+     * `agentSpawnArgs` for the same reason it exists on `SubagentRunInput`: a parent's deny is inherited,
+     * its allowlist is not.
+     */
+    denyTools?: readonly string[];
+    /** Cancels this run. Also cancelled by `abortAll`, so a caller may pass either or both. */
+    signal?: AbortSignal;
+};
+/** What the recorder needs from the server around it. Injected, so this file holds no globals of its own. */
+export type SubagentRunHooks = {
+    store: Store;
+    /**
+     * Publishes one event to whoever is listening. Kept as a plain function rather than a socket set so
+     * this file can be tested with an array, and so a second consumer (a future HTTP probe, say) can be
+     * attached without changing the recorder.
+     */
+    broadcast: (event: ServerEvent) => void;
+    /**
+     * Builds the host that answers a CHILD's questions, keyed by the run as well as the conversation
+     * (design §4). Optional because a headless caller has nobody to ask; a child that asks in that case is
+     * cancelled, never guessed at.
+     */
+    host?: (conversationId: string, runId: string) => ExtensionUiHost;
+};
+export declare class SubagentRunRecorder {
+    private readonly supervisor;
+    private readonly hooks;
+    /**
+     * One entry per in-flight run, so `abortAll` reaches children the caller cannot name and `stop` can
+     * reach one the caller CAN.
+     *
+     * The conversation id is carried alongside the controller rather than looked up from the supervisor's
+     * live view, for two reasons that are really one: the supervisor's entry is deleted the moment the
+     * run settles (so it is absent exactly when a stop is most likely to be sent - the card reacting to
+     * a late click), and `run.stop` needs the CONVERSATION a run belongs to, which only the recorder
+     * knows before the supervisor is asked.
+     */
+    private readonly controllers;
+    constructor(supervisor: SubagentSupervisor, hooks: SubagentRunHooks);
+    /** Every child still running, optionally narrowed to one conversation. The supervisor owns the pids. */
+    liveRuns(conversationId?: string): {
+        id: string;
+        conversationId: string;
+        pid: number | undefined;
+    }[];
+    /**
+     * Stops ONE run, and says whether there was anything to stop.
+     *
+     * THIS IS THE BUTTON THE 32B GAP LEFT OPEN. `run.stop` used to abort the conversation's own Pi and
+     * nothing else, so a sub-agent the user could see on screen kept running - and kept holding the
+     * workspace directory - after they pressed stop. The abort here is the SAME signal the supervisor
+     * turns into an `abort` write followed by `killTree` on Windows, so stopping one really does reach
+     * the grandchild Pi rather than only the `.cmd` shim.
+     *
+     * `false` for an unknown or already-settled id is deliberate, not a swallowed failure: the click
+     * that produces it raced the run's own terminal `subagent.event`, and an `error` reply for that
+     * would put a failure banner on top of a card that says it finished normally.
+     */
+    stop(runId: string): boolean;
+    /**
+     * Stops every run in flight for one conversation, and returns how many were signalled.
+     *
+     * What `run.stop` on a conversation now does to the children it started, so the conversation's own
+     * stop button and a sub-agent card's stop button end the same way. Same reason for the return value
+     * as `stop`: it is a count the caller can log, not an error.
+     */
+    stopConversation(conversationId: string): number;
+    /**
+     * Aborts every run in flight.
+     *
+     * Called on shutdown, and the reason it is worth having: a child left running when the server exits
+     * keeps holding its workspace directory, and Windows will then refuse to delete it. Startup
+     * reconciliation cleans up the RECORD of such a run; this stops the PROCESS from being one.
+     */
+    abortAll(): void;
+    /**
+     * Runs one sub-agent, recording it from before the spawn to after the settle, and returns the record
+     * as it ended.
+     *
+     * ALWAYS RESOLVES, including for a dispatch that never started - an unknown agent, a deleted workspace,
+     * a Pi that is not installed. By the time `run()` is called the `running` record is already written, so
+     * the honest account of "this never ran" is a record that says exactly why, next to the runs that did.
+     * Rejecting instead would leave that row claiming to be running until the next restart, which is the
+     * orphan this whole file is about.
+     *
+     * A caller that wants the child's answer rather than a verdict reads `status` and `output` off the
+     * returned record; it does not pattern-match an error message to find out whether work happened.
+     */
+    dispatch(input: SubagentDispatch): Promise<SubagentRun>;
+}

package/dist/server/subagent-runs.js

@@ -0,0 +1,315 @@
+import { SubagentCancelled, newSubagentRunId } from "./subagents.js";
+/**
+ * Making one sub-agent run VISIBLE and RECOVERABLE, per
+ * [docs/SUBAGENT-DESIGN.md](../../docs/SUBAGENT-DESIGN.md) §5-§6.
+ *
+ * `subagents.ts` spawns and drains; this file remembers and publishes. The split is the same one Part 1
+ * drew: a spawner that also wrote records would have to be tested against a store to prove it streams,
+ * and a store that also spawned children could not be tested without one. Everything here is about the
+ * two obligations the design names and nothing else:
+ *
+ * 1. **A record before the child.** Written as `running` BEFORE `run()` is called, so a server that dies
+ *    mid-run leaves an orphan - and `Store.open` fails that orphan with a reason on the next start.
+ * 2. **A snapshot on every delta.** `subagent.event` carries the run as it stands, not just at the end,
+ *    because streaming a sub-agent is the entire reason Super Pi spawns its own instead of shipping Pi's
+ *    extension (design §2, reason 1).
+ *
+ * What deliberately does NOT go into either is the child's transcript. See `SubagentRun`.
+ */
+/**
+ * The model-visible output cap, 50 KB - design doc §6's `PER_TASK_OUTPUT_CAP`, taken from the reference
+ * implementation (`index.ts:36`) rather than invented here.
+ *
+ * APPLIED TO THE STORED COPY ONLY. A human looking at a sub-agent is debugging it, and trimming its
+ * answer to fit somebody else's context window is the wrong trade for them; the browser gets every byte
+ * through `subagent.event`, and `outputTruncated` is what tells a reader the stored copy is less than
+ * what was said. The parent model is handed the capped copy, because that is the window it actually has.
+ */
+export const PER_TASK_OUTPUT_CAP = 50 * 1024;
+export class SubagentRunRecorder {
+    supervisor;
+    hooks;
+    /**
+     * One entry per in-flight run, so `abortAll` reaches children the caller cannot name and `stop` can
+     * reach one the caller CAN.
+     *
+     * The conversation id is carried alongside the controller rather than looked up from the supervisor's
+     * live view, for two reasons that are really one: the supervisor's entry is deleted the moment the
+     * run settles (so it is absent exactly when a stop is most likely to be sent - the card reacting to
+     * a late click), and `run.stop` needs the CONVERSATION a run belongs to, which only the recorder
+     * knows before the supervisor is asked.
+     */
+    controllers = new Map();
+    constructor(supervisor, hooks) {
+        this.supervisor = supervisor;
+        this.hooks = hooks;
+    }
+    /** Every child still running, optionally narrowed to one conversation. The supervisor owns the pids. */
+    liveRuns(conversationId) {
+        return this.supervisor.liveRuns(conversationId);
+    }
+    /**
+     * Stops ONE run, and says whether there was anything to stop.
+     *
+     * THIS IS THE BUTTON THE 32B GAP LEFT OPEN. `run.stop` used to abort the conversation's own Pi and
+     * nothing else, so a sub-agent the user could see on screen kept running - and kept holding the
+     * workspace directory - after they pressed stop. The abort here is the SAME signal the supervisor
+     * turns into an `abort` write followed by `killTree` on Windows, so stopping one really does reach
+     * the grandchild Pi rather than only the `.cmd` shim.
+     *
+     * `false` for an unknown or already-settled id is deliberate, not a swallowed failure: the click
+     * that produces it raced the run's own terminal `subagent.event`, and an `error` reply for that
+     * would put a failure banner on top of a card that says it finished normally.
+     */
+    stop(runId) {
+        const entry = this.controllers.get(runId);
+        if (!entry)
+            return false;
+        entry.controller.abort();
+        return true;
+    }
+    /**
+     * Stops every run in flight for one conversation, and returns how many were signalled.
+     *
+     * What `run.stop` on a conversation now does to the children it started, so the conversation's own
+     * stop button and a sub-agent card's stop button end the same way. Same reason for the return value
+     * as `stop`: it is a count the caller can log, not an error.
+     */
+    stopConversation(conversationId) {
+        let stopped = 0;
+        for (const entry of this.controllers.values())
+            if (entry.conversationId === conversationId) {
+                entry.controller.abort();
+                stopped += 1;
+            }
+        return stopped;
+    }
+    /**
+     * Aborts every run in flight.
+     *
+     * Called on shutdown, and the reason it is worth having: a child left running when the server exits
+     * keeps holding its workspace directory, and Windows will then refuse to delete it. Startup
+     * reconciliation cleans up the RECORD of such a run; this stops the PROCESS from being one.
+     */
+    abortAll() {
+        for (const entry of this.controllers.values())
+            entry.controller.abort();
+    }
+    /**
+     * Runs one sub-agent, recording it from before the spawn to after the settle, and returns the record
+     * as it ended.
+     *
+     * ALWAYS RESOLVES, including for a dispatch that never started - an unknown agent, a deleted workspace,
+     * a Pi that is not installed. By the time `run()` is called the `running` record is already written, so
+     * the honest account of "this never ran" is a record that says exactly why, next to the runs that did.
+     * Rejecting instead would leave that row claiming to be running until the next restart, which is the
+     * orphan this whole file is about.
+     *
+     * A caller that wants the child's answer rather than a verdict reads `status` and `output` off the
+     * returned record; it does not pattern-match an error message to find out whether work happened.
+     */
+    async dispatch(input) {
+        // `dispatchedBy` defaults to "human" because every caller that existed before the task tool was a
+        // person pressing the button, and the model's own calls are the exception that must be marked.
+        const { conversationId, agentId, task, cwd, model, denyTools, dispatchedBy = "human" } = input;
+        // Generated HERE, not by `run()`, because the record has to exist first - see this file's header.
+        const id = input.id ?? newSubagentRunId();
+        const started = { id, conversationId, agentId, task, dispatchedBy, parentRunId: input.parentRunId, depth: input.depth ?? 0, loopId: input.loopId, role: input.role, status: "running", startedAt: new Date().toISOString(), sessionId: id };
+        await this.hooks.store.beginSubagentRun(started);
+        // The recorder's own copy, held separately from the store's. Mutating the object `beginSubagentRun`
+        // was handed would reach into the store's state behind its back, and every snapshot it hands out
+        // would then move under its reader.
+        const record = { ...started };
+        /** The child's deltas so far. Persisted on every one, exactly as a conversation's assistant text is. */
+        let streamed = "";
+        /**
+         * Tools the child has started, oldest first. Accumulated here rather than taken from the record,
+         * for the same reason `streamed` is: the recorder's copy is what a snapshot is built from, so
+         * mutating the store's object would move it under every reader.
+         */
+        let toolCalls = [];
+        /**
+         * Pi's tool-call id → the row it became, so a `tool_execution_end` can find the call it belongs to.
+         *
+         * Held here rather than on the record, because `SubagentToolCall` deliberately carries no id: card
+         * rows are ordered, not addressable, and an id on a persisted row would be an identity nothing
+         * outside Pi can resolve. The mapping only has to survive the run, which is exactly its scope.
+         */
+        const toolRowById = new Map();
+        /**
+         * What the child was doing last, or undefined while it has done nothing observable yet.
+         *
+         * The gap this exists for is a card that FREEZES: a run that spends its whole life inside one long
+         * tool call emits no `text_delta`, so a browser watching only the text sees nothing change and
+         * cannot tell a working child from a dead one. `at` is what lets the card say how stale the news is.
+         */
+        let activity;
+        /**
+         * The phase the child last reached. Starts at `dispatch`, which covers every refusal before the spawn
+         * and is what a card should say about a run whose child never existed. See `SubagentFailure`.
+         */
+        let stage = "dispatch";
+        const publish = () => {
+            record.output = streamed;
+            record.toolCalls = toolCalls;
+            record.activity = activity;
+            // WRITE BEFORE ANNOUNCE, and this is the whole defect. The order of the two statements below is
+            // load-bearing; swapping them back reintroduces a card that loses text it already streamed.
+            //
+            // The hook a caller installs announces the event and THEN broadcasts `state` (`index.ts`), so both
+            // frames leave here in that order whatever this function does internally. Announcing first made the
+            // `state` frame a snapshot of a store this delta had not reached yet - the write below had not even
+            // been CALLED. The browser REPLACES on `state` (`App.tsx`), so a card that had just been handed the
+            // right text had it taken back one frame later.
+            //
+            // Why some cards lived anyway and this one did not: a child that keeps talking recovers by accident,
+            // because its NEXT delta publishes a `state` once the write queue has drained. A child that says one
+            // thing and goes quiet never publishes again, so nothing restores it - and it is not only that child's
+            // card. Every later `state` broadcast from any command, including ones about an unrelated
+            // conversation, reads that same stale record.
+            //
+            // The write is still not awaited, and still must not be: `onTextDelta` is synchronous, and a drain loop
+            // that flushed to disk per token would throttle the child. Reordering buys the correctness anyway,
+            // because `Store.setSubagentRun` applies its patch BEFORE its first `await` - the same adjacency
+            // `claimQueuedMessage` relies on to make claiming atomic. `Store.snapshot` clones in-memory state
+            // rather than the file, so the frame is correct whether or not the flush behind it has landed yet.
+            const persisted = this.hooks.store.setSubagentRun(id, { output: streamed, toolCalls, activity });
+            this.hooks.broadcast({ type: "subagent.event", run: structuredClone(record) });
+            // Written through on every delta, NOT left until the run settles. `state` is broadcast from other
+            // commands while this run is in flight, and a browser that reloads mid-run reads the record from
+            // there: a store that only saw the final answer would show an empty card and never fill it in until
+            // the child finished. Never rejected into the void, because an unhandled rejection would take the
+            // server down over a write that the next delta is about to make irrelevant.
+            void persisted.catch((error) => {
+                console.warn(`Super Pi: recording a delta of sub-agent run ${id} failed: ${error instanceof Error ? error.message : "unknown error"}`);
+            });
+        };
+        const settle = async (changes) => {
+            Object.assign(record, changes);
+            // PERSIST FIRST, ANNOUNCE SECOND. The order is load-bearing and was previously reversed.
+            //
+            // Broadcasting the terminal frame before the write lands tells the browser a run has finished
+            // while `state.json` still says `running`. Measured, the gap is 0.36-8.19ms - long enough that a
+            // refresh in that window reloads a card that spins forever, and the startup reconciliation that
+            // would fix it only runs on a SERVER restart, not a page refresh. The same principle as
+            // `Store.open` persisting its reconciliation immediately: nothing is announced before it is on
+            // disk. The write is serialized, so the broadcast is a few ms later than it used to be. That is
+            // the correct trade: never announce state that a reload would contradict.
+            const settled = await this.hooks.store.setSubagentRun(id, changes);
+            this.hooks.broadcast({ type: "subagent.event", run: structuredClone(record) });
+            return settled;
+        };
+        /**
+         * Wall-clock from the `running` row to now, in whole milliseconds.
+         *
+         * This project's clock, measured across the row the recorder itself wrote, so it covers the spawn
+         * and the drain rather than only the model's thinking. The point of recording it at all is a
+         * measurement: a real sub-agent reading three files finished in 2.5s, which is far too short for
+         * anyone to have watched it, so without a duration left behind the transcript cannot even say the
+         * run happened.
+         */
+        const elapsedMs = () => Math.max(0, Date.now() - new Date(started.startedAt).getTime());
+        // One controller for both abort sources: the caller's signal and `abortAll` are the same button from
+        // the child's point of view, and `run()` takes exactly one.
+        const controller = new AbortController();
+        this.controllers.set(id, { controller, conversationId });
+        const onCallerAbort = () => controller.abort();
+        input.signal?.addEventListener("abort", onCallerAbort, { once: true });
+        try {
+            const result = await this.supervisor.run({
+                id,
+                conversationId,
+                agentId,
+                task,
+                cwd,
+                model,
+                denyTools,
+                signal: controller.signal,
+                // Asked for BEFORE the run, because the host's key needs the run id and only this file decided it.
+                host: this.hooks.host?.(conversationId, id),
+                onTextDelta: (delta) => {
+                    streamed += delta;
+                    publish();
+                },
+                // Appended, never replaced. `detail` is the DERIVED label `describeToolCall` made from the
+                // child's arguments - one bounded line naming the file, pattern or command - and never the
+                // arguments themselves. `status` stays absent until an `onToolEnd` fills it in, because Pi
+                // announces a tool with `tool_execution_start` and a row with no outcome is exactly how a card
+                // says "this one is still running".
+                onToolCall: (call) => {
+                    toolRowById.set(call.id, toolCalls.length);
+                    toolCalls = [...toolCalls, { label: call.name, ...(call.detail === undefined ? {} : { detail: call.detail }) }];
+                    activity = { kind: "tool", label: call.name, at: new Date().toISOString() };
+                    publish();
+                },
+                // The end of a call, matched back to its row by Pi's own id. A `tool_execution_end` with no
+                // matching start is DROPPED rather than appended: it would otherwise become a row for a call the
+                // card never announced, which reads as a tool the child used that it did not.
+                onToolEnd: (call) => {
+                    const row = toolRowById.get(call.id);
+                    if (row === undefined)
+                        return;
+                    activity = { kind: "thinking", at: new Date().toISOString() };
+                    toolCalls = toolCalls.map((item, index) => index === row
+                        ? { ...item, status: call.status, ...(call.durationMs === undefined ? {} : { durationMs: call.durationMs }) }
+                        : item);
+                    publish();
+                },
+                // Thinking, not tool: the child is alive and composing, and saying so is the only thing that
+                // distinguishes a reasoning model mid-turn from a hung one.
+                onThinking: () => {
+                    activity = { kind: "thinking", at: new Date().toISOString() };
+                    publish();
+                },
+                onStage: (next) => { stage = next; },
+            });
+            // `run()` returns the authoritative last assistant message, which is what the record means by
+            // `output`; the streamed copy is only a fallback for a child that never sent a `done`.
+            const output = result.finalText || streamed;
+            const truncated = output.length > PER_TASK_OUTPUT_CAP;
+            return await settle({
+                status: "completed",
+                output: truncated ? output.slice(0, PER_TASK_OUTPUT_CAP) : output,
+                // `undefined` rather than `false`: the key is absent on an untruncated run, so it serializes
+                // identically to a record written before this field existed.
+                outputTruncated: truncated || undefined,
+                toolCalls,
+                usage: result.usage,
+                sessionId: result.sessionId,
+                durationMs: elapsedMs(),
+                // CLEARED rather than left describing the child's last moment: a finished card that still says
+                // 正在调用 read is making a claim about a process that no longer exists.
+                activity: undefined,
+                failure: undefined,
+                finishedAt: new Date().toISOString(),
+            });
+        }
+        catch (error) {
+            const stopped = error instanceof SubagentCancelled;
+            return await settle({
+                status: stopped ? "stopped" : "failed",
+                // Cleared rather than left as the partial stream: `output` is defined as the last assistant
+                // message, and a run that produced none has none. What the child managed to say is not lost - it
+                // was already broadcast - and `error` says why the run ended without one.
+                output: undefined,
+                outputTruncated: undefined,
+                // KEPT, unlike `output`: which tools the child reached for before it stopped is a true fact about
+                // the run and is usually the whole diagnosis. They are labels and derived targets, never
+                // arguments or results, so §5's rule about the child's turn not entering `state.json` still holds.
+                toolCalls,
+                // WHERE, not only WHAT. `error` says what went wrong; this says which phase the child was in when
+                // it did, so a card can answer 「卡在哪」 - and a run stopped by a person is not given one, because
+                // nobody failed: 「已停止」 is a complete and true account.
+                ...(stopped ? {} : { failure: { stage } }),
+                durationMs: elapsedMs(),
+                activity: undefined,
+                error: stopped ? `Run ${id} was stopped before it settled.` : error instanceof Error ? error.message : "unknown error",
+                finishedAt: new Date().toISOString(),
+            });
+        }
+        finally {
+            input.signal?.removeEventListener("abort", onCallerAbort);
+            this.controllers.delete(id);
+        }
+    }
+}

package/dist/server/subagents.d.ts

@@ -0,0 +1,194 @@
+import { type ExtensionUiHost } from "./runtime.js";
+import { describeToolCall, TOOL_DETAIL_CAP } from "./tool-calls.js";
+import { type ModelSelection, type SubagentFailure, type SubagentUsage } from "./types.js";
+/** Re-exported from `types.js` where it is declared: usage is a PERSISTED shape, not a spawn detail. */
+export type { SubagentUsage };
+/**
+ * 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 };
+/**
+ * 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 declare const newSubagentRunId: () => string;
+/**
+ * One tool the child started, and later ended.
+ *
+ * `detail` is a derived label, not the arguments - see `describeToolCall` in `tool-calls.js`, which is
+ * where that mapping now lives and why. `status` and `durationMs` arrive on the separate `onToolEnd`
+ * callback, because they are facts about the END of a call and a caller that cannot tell the two apart
+ * would have to guess at a half-filled row.
+ */
+export type SubagentToolCall = {
+    id: string;
+    name: string;
+    detail?: string;
+    status?: "ok" | "error";
+    durationMs?: number;
+};
+/**
+ * One completed run.
+ *
+ * `sessionId` is Pi's own session id for the child, which today is the run id because that is what
+ * `--session-id` was given. They are separate fields because they are separate facts: the run is
+ * Super Pi's record, the session is the file Pi wrote, and a future caller (records in step 2) will
+ * want to report one after the other has been changed.
+ */
+export type SubagentResult = {
+    id: string;
+    sessionId: string;
+    finalText: string;
+    usage: SubagentUsage;
+};
+export type SubagentRunInput = {
+    /** The conversation that dispatched this run. Recorded on the child so a later reader can attribute it. */
+    conversationId: string;
+    /** The `agents/*.md` file's base name, which must be a `mode: subagent` definition. */
+    agentId: string;
+    /** What the child is asked to do. Sent over RPC stdin, never on the command line - see `run()`. */
+    task: string;
+    /**
+     * The directory the child must run in: the dispatching conversation's workspace, resolved by the
+     * caller. Required with no default for the same reason `AnswerInput.cwd` is: every tool the child runs
+     * resolves its paths against this directory, so an absent one would silently run the sub-agent in the
+     * server's own directory instead of failing.
+     */
+    cwd: string;
+    /** The parent conversation's current model, used when the definition names none. See `run()`. */
+    model?: ModelSelection;
+    /**
+     * Tools the DISPATCHING agent has denied, removed from this child's allowlist.
+     *
+     * The parent's denies are inherited and its allowlist is NOT, which is exactly what OpenCode's
+     * `deriveSubagentSessionPermission` does and why: "parent agent restrictions only govern that agent;
+     * the subagent's own permissions determine its capabilities" (subagent-permissions.ts:11-12). A
+     * primary agent that took `bash` away from itself has said something about its own turns; a child
+     * whose own author gave it `bash` for verification is not thereby unsafe.
+     *
+     * Applied to the child's `agents/*.md` map by `agentSpawnArgs`, never by editing the definition: two
+     * runs of the same agent under different parents must be able to differ.
+     */
+    denyTools?: readonly string[];
+    /**
+     * The id this run answers to. Omitted means `newSubagentRunId()`.
+     *
+     * Supplied by a caller that must know the id before the child exists - the recorder persists a
+     * `running` row first precisely so a crashed server leaves a reconcilable orphan, which is impossible
+     * if the id only appears after `run()` returns. Validated rather than trusted, because the same string
+     * becomes Pi's `--session-id` and is the key startup reconciliation looks orphans up by: a run
+     * recorded under an id nothing else knows can never be found, let alone cleaned up.
+     */
+    id?: string;
+    /**
+     * Who answers the child's Extension UI questions.
+     *
+     * Absent means nobody can be asked, and a blocking question is CANCELLED - Pi's own third response
+     * shape, meaning "no answer was collected". Auto-answering with `options[0]` would look to Pi exactly
+     * like a decision the user made, and the user would never learn a question was asked of them.
+     */
+    host?: ExtensionUiHost;
+    /** Aborting writes Pi an `abort` and then kills the whole process tree; `run()` rejects with `SubagentCancelled`. */
+    signal?: AbortSignal;
+    /** Called once per `text_delta`, in order, with the raw delta. Never the accumulated text. */
+    onTextDelta?: (delta: string) => void;
+    /** Called on `tool_execution_start`, with the name and the derived target label. */
+    onToolCall?: (call: SubagentToolCall) => void;
+    /**
+     * Called on `tool_execution_end` for the same `id`, carrying how the call ended.
+     *
+     * A SEPARATE callback rather than a second `onToolCall`, so "a tool started" and "a tool finished"
+     * stay distinguishable: a row with no status is a call still in flight, which is the whole reason the
+     * card can show that a child is inside a long tool right now. Nothing here is derived from the
+     * RESULT - only `isError` and Pi's own `durationMs` come through, because a result can be a file.
+     */
+    onToolEnd?: (call: SubagentToolCall) => void;
+    /** Called on every `thinking_delta`: the child is composing, and emitting no output while it does. */
+    onThinking?: () => void;
+    /**
+     * Called when the run moves to a new phase, for a caller that has to report where it died.
+     *
+     * Driven by the drain loop meeting each record family rather than by a timer, so the phase can only
+     * ever be one the supervisor actually observed. `dispatch` is the implicit starting value and is
+     * never announced - a run that fails before the prompt is written never called it, and the caller's
+     * default is the honest answer rather than a special case.
+     */
+    onStage?: (stage: SubagentFailure["stage"]) => void;
+};
+/**
+ * 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 declare class SubagentCancelled extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/** Spawns sub-agent children Pi and drains their JSONL RPC streams. */
+export declare class SubagentSupervisor {
+    private readonly sessionDir;
+    private readonly agents;
+    private readonly pi;
+    /** Live children by run id, so a caller can name the process it means. Cleared in the run's `finally`. */
+    private readonly children;
+    /**
+     * `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: string, command?: string, agents?: {
+        dir: string;
+        promptDir: string;
+    });
+    /**
+     * 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?: string): {
+        id: string;
+        conversationId: string;
+        pid: number | undefined;
+    }[];
+    /**
+     * 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.
+     */
+    run(input: SubagentRunInput): Promise<SubagentResult>;
+    /**
+     * 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.
+     */
+    private subagentDefinition;
+}