@evandu/super-pi 0.0.0-stage → 0.1.0

package/dist/server/runtime.d.ts

@@ -0,0 +1,819 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import { type AgentDefinition, type Conversation, type ExtensionUiAnswer, type ExtensionUiRequest, type MessageImage, type ModelCatalog, type ModelOption, type ModelSelection, type PiQueueSnapshot, type ToolCallNotice } from "./types.js";
+/**
+ * Who answers Pi's Extension UI questions. The runtime never invents an answer: a blocking method
+ * either comes back from `ask`, or it is cancelled. That is the whole point of Pi's third response
+ * shape - `{ type: "extension_ui_response", id, cancelled: true }` means "no answer was collected",
+ * which Pi is entitled to fall back from, whereas a fabricated `options[0]` looks identical to a
+ * human choice and silently discards the question the user was supposed to see.
+ */
+export interface ExtensionUiHost {
+    /** Blocking methods. Must settle only once a human answered, cancelled, or the run ended. */
+    ask(request: ExtensionUiRequest): Promise<ExtensionUiAnswer>;
+    /** One-way methods. Fire and forget: the host must not retain the request, and there is nothing to await. */
+    notify(request: ExtensionUiRequest): void;
+}
+export interface AnswerInput {
+    conversation: Conversation;
+    prompt: string;
+    images?: MessageImage[];
+    signal: AbortSignal;
+    /**
+     * The directory the child process must run in: the conversation's workspace path, resolved by the
+     * caller (the runtime never sees the workspace map). Required with no fallback - every tool Pi runs
+     * resolves its paths against this directory, so a missing one must fail loudly rather than silently
+     * run in the server's directory.
+     */
+    cwd: string;
+    /** Absent in headless use, in which case blocking requests are cancelled rather than guessed at. */
+    host?: ExtensionUiHost;
+    /**
+     * Called for every `queue_update` the child pushes, which is Pi reporting its own in-memory queue.
+     *
+     * Optional and observational: nothing about the delivery contract depends on it. It exists because
+     * `queue_update` (`agent-session.ts:204-208`) is the ONLY proof that a steer was actually picked up -
+     * Pi removes the entry from its queue and emits this snapshot BEFORE it emits the delivered
+     * `message_start` (`agent-session.ts:1116-1136`), so a host that ignored it would have no way to tell
+     * "queued in Pi" from "delivered to the model". It is also why a record that used to be announced as
+     * unhandled and dropped is now read.
+     */
+    onPiQueue?(queue: PiQueueSnapshot): void;
+    /**
+     * Called ONCE per turn with the Pi entry id of the user message that started it, or never.
+     *
+     * This is the whole of Super Pi's ability to name a position inside Pi's transcript, and the window is
+     * one turn long: `answer()` spawns Pi here and kills it in its `finally`, so an id not taken before the
+     * loop ends is not obtainable at all. It is taken from Pi's own `get_entries` (`rpc-mode.ts:636-647`),
+     * not by counting, because Pi writes entry types that are not messages (`model_change`,
+     * `thinking_level_change`, `compaction`, ...) and only Pi knows which line the user message is.
+     *
+     * Failing to produce one is NOT a turn failure - the answer has already streamed by then - so it is
+     * never awaited on the critical path and never thrown. A message with no entry id simply cannot be a
+     * revert boundary, which the revert handler reports in words.
+     */
+    onUserEntry?: (entryId: string) => void | Promise<void>;
+    /**
+     * Called once per `tool_execution_start`, with the tool's name and the bounded label naming what it was
+     * aimed at.
+     *
+     * ABSENT MEANS "DON'T BOTHER", and the record is still consumed rather than announced - see the drain
+     * loop. That is the whole point of this pair: until it existed the PRIMARY agent's tool calls were the
+     * one thing Pi emitted that nobody on this side looked at, so a `read` and a two-minute `bash` were the
+     * same silence on the transcript, and a reader had no way to tell "the agent did nothing" from "the agent
+     * did six things you cannot see".
+     *
+     * The same two facts the sub-agent supervisor already reports, through the same `describeToolCall`
+     * mapping, because the two surfaces are two windows onto one protocol and a `read` labelled by its path
+     * on a card but by its working directory on a call block would be worse than having neither.
+     */
+    onToolCall?(call: ToolCallNotice): void;
+    /**
+     * Called on `tool_execution_end` for the same `id`, carrying how the call ended.
+     *
+     * A SEPARATE callback for the same reason the supervisor has one: "a tool started" and "a tool finished"
+     * are distinguishable events, and a caller that could not tell them apart would have to invent the second
+     * one - which would be a row claiming an outcome Pi never reported.
+     *
+     * ONLY `isError` AND `durationMs` CROSS OVER. `result` is deliberately never read, for the reason
+     * `RpcRecord` does not even declare it: for a `read` it is the file's contents, and this type is the one
+     * place a reader would reach for it.
+     */
+    onToolEnd?(call: ToolCallNotice): void;
+}
+/**
+ * What Pi answered when a `steer` was written to it, from the `disposition` of that command's response
+ * (`rpc-mode.ts:416-419`).
+ *
+ * - `handled` - Pi delivered it immediately, because there was no turn to wait for. Super Pi can drop it
+ *   from its own list right away.
+ * - `queued`  - Pi is holding it and will take it at the next turn boundary. It stays in Super Pi's list
+ *   as `sending` until `queue_update` reports it gone.
+ *
+ * This is a real distinction and not a detail: it is the difference between a message that is already
+ * in the model's context and one that is not, and the UI must not claim either without knowing which.
+ */
+export type SteerDisposition = "handled" | "queued";
+/**
+ * What a revert has to be told, and what it is told afterwards. Declared here rather than in `types.ts`
+ * because neither travels to the browser: this is the runtime's own account of a file it changed.
+ */
+export type RevertRequest = {
+    /** The conversation being reverted. Its `id` is Pi's `--session-id`, and is what identifies the file. */
+    conversation: Conversation;
+    /**
+     * The directory the next turn would spawn Pi in - the conversation's workspace.
+     *
+     * NOT OPTIONAL and NOT DEFAULTED, because it decides WHICH FILE IS FOUND: Pi's own `findById`
+     * (`session-manager.ts:1874-1891`) only matches a session whose recorded `cwd` equals the one it is
+     * asked from, and probe B measured that: the same id opened from two different cwds resolved to two
+     * different files, one of which did not exist. Passing the server's own directory here would find no
+     * conversation at all, and passing the wrong workspace would find somebody else's.
+     */
+    cwd: string;
+    /** Pi's entry id of the last message that SURVIVES. Everything written after it is dropped. */
+    boundaryEntryId: string;
+};
+export type RevertOutcome = {
+    /** The file that was truncated, so a caller can log what was rewritten. */
+    sessionFile: string;
+    /** Lines kept, header included. The boundary line is the last of them. */
+    linesKept: number;
+    /** Entry lines dropped. Zero means the boundary was already the leaf. */
+    entriesDropped: number;
+};
+/** What a fork has to be told, and what it is told afterwards. See `RevertRequest` for why these are here
+ *  rather than in `types.ts`: neither travels to the browser - this is the runtime's own account of a file
+ *  it wrote. */
+export type ForkRequest = {
+    /** The conversation being forked. Its `id` is Pi's `--session-id`, and is what identifies the file. */
+    conversation: Conversation;
+    /** The same directory the next turn would spawn Pi in - the conversation's workspace. Required for the
+     *  same reason as `RevertRequest.cwd`: Pi's own lookup only matches a session whose recorded `cwd`
+     *  equals the one it is asked from, so getting this wrong resolves to some other conversation's file. */
+    cwd: string;
+    /**
+     * The id the NEW conversation will have, minted by the store BEFORE the file is written.
+     *
+     * MINTED UP FRONT RATHER THAN BY THE RUNTIME, and the ordering is the safety property: this file's
+     * header `id` has to BE the new conversation's id, so the id must exist before a byte is written - but
+     * the conversation itself must not exist until the file is safely on disk. Minting here and creating
+     * after gives exactly that: a write failure leaves an unreferenced `.jsonl` (inert - Pi only ever opens
+     * a file by an id some conversation already claims), while the reverse order would leave a conversation
+     * whose model context is silently empty, which is the single worst outcome available here.
+     */
+    forkedConversationId: string;
+};
+export type ForkOutcome = {
+    /** The file that was written, so a caller can log it. Absent when the source had no Pi transcript at
+     *  all - an empty conversation - and the fork is then a copy of `state.json` alone. */
+    sessionFile?: string;
+    /** Entry lines copied, header excluded. */
+    entriesCopied: number;
+};
+export interface AgentRuntime {
+    answer(input: AnswerInput): AsyncIterable<string>;
+    stop?(conversationId: string): Promise<void>;
+    /**
+     * Hands one message to the Pi process that is running RIGHT NOW, to be injected at its next turn
+     * boundary (`agent-loop.ts:295`) rather than after the whole task.
+     *
+     * Resolves with Pi's own answer, and REJECTS when there is no live child or Pi did not answer. Rejecting
+     * rather than silently succeeding is what lets the caller keep the message cancellable: a steer that
+     * never reached a Pi process provably reached no model, while a steer that was written but not
+     * confirmed is genuinely unknown and must not be reported as either delivered or failed.
+     *
+     * Absent on a runtime with no Pi behind it (the welcome runtime), which has nothing to steer.
+     */
+    steer?(conversationId: string, message: string, images?: MessageImage[]): Promise<SteerDisposition>;
+    /**
+     * The agent a conversation runs as, read fresh from the agent directory. Absent on a runtime with
+     * no agents (the welcome runtime), where every conversation runs as Pi itself. Callers that need an
+     * agent's declared model - to apply it when one is selected - go through here rather than reading the
+     * directory themselves, so the picker and the spawn can never disagree about which definition is live.
+     */
+    agentFor?(conversation: Pick<Conversation, "id" | "agentId">): Promise<AgentDefinition | undefined>;
+    /**
+     * The model/thinking catalog a picker lists. `selection` scopes the answer to one model's
+     * capabilities, because Pi's thinking levels are per model (`getSupportedThinkingLevels`,
+     * ai/src/models.ts:1224): a catalog taken from the default model would offer levels that the
+     * selected model silently clamps away.
+     */
+    catalog(selection?: ModelSelection): Promise<ModelCatalog>;
+    /**
+     * Reverts the conversation to the state right after `boundaryEntryId`, in Pi's own transcript.
+     *
+     * OPTIONAL on the interface, like `stop`, because a runtime with no Pi has no Pi transcript to cut -
+     * and the handler must not pretend otherwise. A runtime that cannot revert says so; it never silently
+     * does nothing, which would leave `state.json` and the model's context permanently disagreeing while
+     * the UI showed a perfectly successful revert.
+     */
+    revert?(request: RevertRequest): Promise<RevertOutcome>;
+    /**
+     * Writes a SECOND Pi transcript that starts as an exact copy of one conversation's, under a different
+     * session id.
+     *
+     * OPTIONAL on the interface for the same reason `revert` is: a runtime with no Pi behind it has no Pi
+     * transcript to copy. But the asymmetry matters - a revert that cannot happen is merely refused, whereas
+     * a fork that quietly produced only a `state.json` copy would hand the user a conversation that LOOKS
+     * complete and whose model has never heard any of it. So the absence of this method is reported as a
+     * refusal, exactly as `revert`'s absence is, rather than passed over.
+     */
+    fork?(request: ForkRequest): Promise<ForkOutcome>;
+}
+/** Deterministic offline runtime used by tests and local UI development. */
+export declare class WelcomeRuntime implements AgentRuntime {
+    answer({ prompt, signal }: AnswerInput): AsyncIterable<string>;
+    stop(): Promise<void>;
+    /**
+     * No Pi, so no models. `source` is what turns the picker into a visibly disabled control instead
+     * of an empty list, which would read as "you have no models".
+     */
+    catalog(): Promise<ModelCatalog>;
+}
+/**
+ * One record off Pi's JSONL stdout. Deliberately a loose shape with optional fields: Pi emits a wide,
+ * open-ended family of session events, and a type that enumerated all of them would break on the next
+ * Pi release rather than on the next behaviour change.
+ *
+ * Exported so another consumer of `RpcChannel` - the sub-agent supervisor - can read the same records
+ * through the same channel instead of writing a second JSONL reader. Every field below is optional, so
+ * a reader must check before using one.
+ */
+export type RpcRecord = {
+    type?: string;
+    id?: string;
+    success?: boolean;
+    error?: string;
+    /** Every `response` record's payload. Kept opaque: only the catalog reader knows these shapes. */
+    data?: unknown;
+    /**
+     * The inner event of a `message_update`. `message` rides on `done` - the authoritative final
+     * assistant message, with its text content, its stop reason and its model (pi-ai AssistantMessageEvent).
+     */
+    assistantMessageEvent?: {
+        type?: string;
+        delta?: string;
+        reason?: string;
+        message?: {
+            role?: string;
+            content?: unknown;
+            stopReason?: string;
+            model?: string;
+        };
+    };
+    /**
+     * Cumulative usage of the CURRENT assistant message, repeated on every one of that message's updates
+     * (modes/json-event.ts:56-59). Reading it anywhere but on `done` counts the same tokens per token.
+     */
+    usage?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        cost?: {
+            total?: number;
+        };
+    };
+    toolCallId?: string;
+    toolName?: string;
+    args?: unknown;
+    /**
+     * tool_execution_end payload. `result` is NOT declared: it is deliberately never read, because for a
+     * `read` it is the file's contents and this type is the one place a reader would reach for it. The two
+     * numbers below are the whole of what a human-readable tool row can honestly report.
+     */
+    isError?: boolean;
+    durationMs?: number;
+    method?: string;
+    title?: string;
+    options?: unknown;
+    message?: string;
+    placeholder?: string;
+    prefill?: string;
+    timeout?: number;
+    notifyType?: string;
+    statusKey?: string;
+    statusText?: string;
+    widgetKey?: string;
+    widgetLines?: unknown;
+    widgetPlacement?: string;
+    text?: string;
+    extensionPath?: string;
+    event?: string;
+    steering?: unknown;
+    followUp?: unknown;
+};
+/**
+ * Reads Pi's `queue_update` payload, or returns undefined when the record is not one.
+ *
+ * Filters to real strings rather than passing the arrays through, so a malformed snapshot cannot put
+ * objects into the browser's DOM or into a log line that is supposed to be readable - the same rule
+ * `textList` already applies to Extension UI options. Returns undefined for the wrong `type` too, so the
+ * drain loop can keep using it as the recogniser.
+ */
+export declare function describePiQueue(record: RpcRecord): PiQueueSnapshot | undefined;
+/** A line to write back to Pi's stdin. Mirrors Pi's RpcExtensionUIResponse union (rpc-types.ts:294-297). */
+export type ExtensionUiResponse = {
+    type: "extension_ui_response";
+    id: string;
+    value?: string;
+    confirmed?: boolean;
+    cancelled?: true;
+};
+/**
+ * Normalizes one `extension_ui_request` record, or returns undefined when the record is not something
+ * Pi's union can produce (wrong `type`, missing `id`, or a method outside the nine). Exports so the
+ * mapping can be tested without spawning Pi.
+ */
+export declare function describeExtensionUiRequest(record: RpcRecord): ExtensionUiRequest | undefined;
+/**
+ * Maps a human's answer onto the one response shape Pi's method accepts. The method decides the shape
+ * rather than the answer, so a client that sends `confirmed` for a `select` (or `value` for a `confirm`)
+ * cannot produce a response Pi would read as a missing field.
+ */
+export declare function buildExtensionUiResponse(request: ExtensionUiRequest, answer: ExtensionUiAnswer): ExtensionUiResponse;
+/** One Pi child, its stdout reader, and the single writer to its stdin. */
+export declare class RpcChannel {
+    private readonly child;
+    private readonly records;
+    /**
+     * Responses a drain loop pulled off the queue before the waiter that wanted them looked.
+     *
+     * THE RACE THIS EXISTS TO SETTLE, and it is not a rare one - it cost this file an intermittent test
+     * failure. One queue serves two kinds of reader: `waitFor`, which is after a specific command's answer by
+     * id, and `next`, which is a turn's drain loop reading whatever arrives first. The loop does not know
+     * which ids someone is waiting for, so it used to take the first record of any kind - including the answer
+     * to a `get_entries` written moments earlier - and the waiter then waited out its whole timeout for a
+     * response that had already been consumed and discarded.
+     *
+     * So the drain loop no longer decides an unmatched response is garbage: it HANDS IT BACK here, and the
+     * waiter finds it whether it got there first or second. Nothing is dropped, and nothing is waited for
+     * twice.
+     */
+    private readonly stashed;
+    private buffer;
+    /** stderr is kept only to explain an early exit; a well-behaved Pi writes nothing here. */
+    stderr: string;
+    constructor(child: ChildProcessWithoutNullStreams);
+    get exitCode(): number | null;
+    /** Writes one JSONL command. Throws rather than silently dropping: a command Pi never sees is a lie the caller would act on. */
+    write(command: object): void;
+    /**
+     * Returns one record to whoever is waiting for it, after a drain loop read it.
+     *
+     * Called for every response the loop does not consume itself. See `RpcChannel`'s note on `stashed` for why
+     * this is not the same as discarding it - discarding it silently cost a turn its revert boundary.
+     */
+    stash(record: RpcRecord): void;
+    /** Removes and returns the next record, or undefined after `timeoutMs` with nothing to read. */
+    next(timeoutMs?: number): Promise<RpcRecord | undefined>;
+    /** Sends a command and waits for its response. For one command; use write()+waitFor() to overlap several. */
+    request(command: {
+        id: string;
+        type: string;
+    } & Record<string, unknown>, timeoutMs: number): Promise<RpcRecord>;
+    /**
+     * Returns one response by id, from the queue if it is still there and from the stash if a drain loop got
+     * there first. Removing it from the stash is what keeps a single answer from being handed out twice.
+     */
+    private take;
+    /**
+     * Waits for the response to one command id. Every record that is not that response stays QUEUED in
+     * order, so a caller can have three requests in flight and still read all three answers: whoever
+     * asks first takes its own record and leaves the rest for the drain loop.
+     */
+    waitFor(id: string, timeoutMs: number, what?: string): Promise<RpcRecord>;
+}
+/**
+ * The commands a freshly spawned Pi must be told before it runs a conversation's turn.
+ *
+ * This is the whole mechanism behind the picker: PiRpcRuntime spawns one Pi process per turn and
+ * kills it afterwards, so there is no long-lived session to poke. Writing these commands onto that
+ * process's stdin before the prompt is what makes a selection REAL - Pi answers `set_model` with
+ * the model it switched to, and the prompt that follows runs on it.
+ *
+ * Model BEFORE level, and the order is load-bearing: `AgentSession.setModel` re-derives the thinking
+ * level for the new model (agent-session.ts:2493), so applying the level first would have Pi undo it
+ * on the very next line.
+ *
+ * A conversation with neither selection produces NO commands, which is what keeps every
+ * pre-picker conversation on Pi's own defaults.
+ */
+export declare function sessionCommands(conversation: Pick<Conversation, "model" | "thinkingLevel">): {
+    id: string;
+    type: string;
+}[];
+/**
+ * Kills a whole process tree on Windows. Pi is launched through a .cmd shim (spawn with shell:true),
+ * so the spawned process is cmd.exe and the real Pi is its grandchild: killing the shim alone leaks
+ * Pi, which keeps holding its working directory and the RPC pipes. No-op on a pid that already died.
+ *
+ * Exported rather than reimplemented per spawner: a second copy is how one of the two ends up killing
+ * only the shim, which is the exact failure this function exists to prevent.
+ */
+export declare function killTree(pid: number): Promise<void>;
+/**
+ * Cuts a Pi session file down to the header plus everything up to and including `boundaryEntryId`.
+ *
+ * ============================ WHAT THIS DESTROYS ============================
+ * **Every entry written after the boundary is gone from disk, permanently, and there is no way to
+ * reconstruct it from this file.** That includes not only the messages a person can see but also Pi's
+ * `tool_call` records, `compaction` summaries, `model_change` and `thinking_level_change` markers, usage
+ * accounting, and anything a future Pi version adds. This is the step the whole revert design is built
+ * around (research §4.2) and the step that cannot be undone by the application - Super Pi has no undo,
+ * and adding one was explicitly left out of scope.
+ *
+ * It does NOT touch the workspace. No file the agent read or wrote is read, written or reverted here.
+ * =============================================================================
+ *
+ * WHY TRUNCATE RATHER THAN ASK PI. Pi's `SessionManager` is append-only by design
+ * (`session-manager.ts:1516-1519`: "Entries cannot be modified or deleted"), and its in-session rewind -
+ * `branch()`, `navigateTree()` - is IN-MEMORY ONLY (`:1573-1584`): `_buildIndex()` re-reads the whole
+ * file on every `open()` and sets the leaf to the last line unconditionally (`:1103-1122`). Super Pi
+ * spawns one Pi per turn and kills it afterwards, so a leaf pointer set in one turn is gone before the
+ * next one starts - a "call `branch()` once" solution would look correct for a turn and then silently
+ * forget (research §5 pitfall 2). Truncating the file is the only version of this that is a durable state
+ * change rather than per-turn bookkeeping that can be skipped exactly once.
+ *
+ * WHY THE FORMAT IS ASSUMED RATHER THAN GUESSED. The shape this relies on - line 0 is the one and only
+ * `type: "session"` header, every other line is one self-contained JSON entry, every entry's `parentId`
+ * already appears earlier in the file, no blank lines, and a trailing newline - was measured against
+ * real Pi by scripts/probe-revert-session-format.mjs, which also proves the `parentId` property that
+ * makes a prefix a VALID session rather than a fragment. That probe is the reason this function may
+ * index by line at all; every one of those claims is re-checked here before anything is written, so a
+ * Pi that changed the format fails loudly instead of producing a file Pi cannot open.
+ *
+ * WHY THE WRITE IS TEMP-THEN-RENAME. Pi appends with a bare `appendFileSync`
+ * (`session-manager.ts:1187`) and makes no atomicity guarantee of its own. Writing the truncated copy
+ * under a different name and renaming it over the original means a reader never observes a half-written
+ * file, and a failure before the rename leaves the original untouched.
+ *
+ * WHY A BACKUP IS KEPT. `.super-pi-revert-backup` is written next to the session file, deliberately not
+ * named `*.jsonl` so Pi's own discovery (`readdirSync` filtered on that suffix,
+ * `session-manager.ts:1881`) never lists it, and deliberately NOT surfaced anywhere as a feature:
+ * Super Pi has no undo and does not pretend to. It exists so that an irreversible, unrecoverable-by-code
+ * operation on a person's conversation history is at least recoverable by hand.
+ *
+ * EXPORTED so it can be tested against a fabricated session file in a temp directory, without Pi and
+ * without touching anybody's real transcript.
+ */
+export declare function truncateSessionFile(path: string, boundaryEntryId: string, expectedSessionId: string): Promise<{
+    linesKept: number;
+    entriesDropped: number;
+}>;
+/**
+ * Writes a second Pi session file that begins as an EXACT copy of one, under a different session id.
+ *
+ * ============================ WHAT THIS DOES TO THE ORIGINAL ============================
+ * **Nothing.** The source file is read and never written, never truncated, never renamed. This is the
+ * whole difference from `truncateSessionFile`, and it is the reason a fork is the safe half of this pair
+ * of operations: a revert destroys entries permanently and keeps a hand-recovery backup, while a fork
+ * leaves both files whole and keeps no backup because there is nothing to recover.
+ * ========================================================================================
+ *
+ * WHY A COPY AND NOT PI'S `fork()`. Covered at length on `ClientCommand`'s `conversation.fork`: Pi's fork
+ * always tears down the runtime and switches to the new session (`agent-session-runtime.ts:299-307`), and
+ * Super Pi has no runtime to switch - it spawns one Pi per turn and kills it. The file is the only durable
+ * thing a fork has to produce here, so the file is what gets produced.
+ *
+ * ============================ WHAT THIS DOES TO PI's ENTRY IDS ============================
+ * **Nothing either, and this is a deliberate divergence from Pi's own `createBranchedSession`, which
+ * RENUMBERS `parentId` (`:1655-1666`).** Keeping every id verbatim means every cross-reference already
+ * inside the file stays valid, and research pitfall 6 is exactly why that matters: a Pi entry may point
+ * at other entries by id in ways this code has never enumerated - a `compaction` record carries a
+ * `firstKeptEntryId`, `branch_summary` carries the branch point - and renumbering ids means rewriting every
+ * one of those references correctly, with no way to find them all. Copying the bytes cannot break a
+ * reference because it changes nothing a reference points at. The cost is that the same entry id now
+ * exists in two files; that is safe because `_buildIndex` builds its `byId` map per file (`:1103-1122`),
+ * and Super Pi only ever opens one file per process.
+ *
+ * WHAT THE HEADER CHANGES, and it is two fields. `id` becomes the new conversation's id, because that is
+ * what Pi's lookup matches (`findLocalSessionByExactId` reads the header, probe B) and therefore what makes
+ * `--session-id <forked>` open THIS file rather than silently inventing an empty session with that id
+ * (`main.ts:436-448`, measured: `Warning: No project session found with id '...'`). And `parentSession`
+ * records the file this one came from, which is the same one-line lineage pointer Pi itself writes
+ * (`:1675-1682`) and is not a link - the files share nothing. `cwd`, `version` and `timestamp` are copied
+ * verbatim: `cwd` MUST be identical, because Pi's lookup requires the recorded cwd to equal the one it is
+ * asked from, and the fork always lives in the same workspace as its source.
+ *
+ * THE SAME FORMAT CHECKS AS TRUNCATE, AND FOR THE SAME REASON. Probe A measured this file's shape against
+ * real Pi (`scripts/probe-revert-session-format.mjs`); a Pi upgrade can invalidate any of those claims, so
+ * every one is re-checked before a byte is written and a failure names the shape actually found. Here the
+ * `parentId` property is checked across the WHOLE file rather than across a kept prefix, because the whole
+ * file is what is being copied.
+ *
+ * TEMP-THEN-RENAME, because Pi appends with a bare `appendFileSync` (`:1187`) and the target must never be
+ * observed half-written - a half-written file under the forked id is precisely the "Pi opens an empty
+ * session and the history has vanished with no error anywhere" outcome probe B was about.
+ *
+ * EXPORTED so it can be tested against fabricated session files in a temp directory, without Pi.
+ */
+export declare function forkSessionFile(sourcePath: string, targetPath: string, expectedSessionId: string, targetSessionId: string): Promise<{
+    entriesCopied: number;
+}>;
+/**
+ * Reads Pi's `steer` disposition out of its response payload.
+ *
+ * Unknown and missing both become `queued`, which is the CONSERVATIVE default and not a convenience: a
+ * steer Pi could not categorise may or may not already be in the model's context, so it must keep being
+ * treated as "not yet delivered" until a `queue_update` says otherwise. Guessing `handled` would let the
+ * caller drop the message from the dock on the strength of a payload shape we did not recognise.
+ */
+export declare function describeSteerDisposition(data: unknown): SteerDisposition | undefined;
+/** Keys Pi's model answers by. Exported so the store and the tests agree with the runtime. */
+export declare const catalogKey: (selection?: ModelSelection) => string;
+/**
+ * Where the `task` extension lives, as an ABSOLUTE path.
+ *
+ * Absolute because Pi requires it: `--extension` takes the path verbatim and resolves it against Pi's
+ * own working directory, which is the CONVERSATION's workspace, not this repository. A relative path
+ * would therefore resolve differently for every conversation and fail for all of them except the one
+ * whose workspace happens to be this repo.
+ *
+ * `import.meta.dirname` is the one thing stable across both ways this code runs - `dist/server/` after
+ * `tsc -b`, `src/server/` under `tsx watch` - so two `..` segments reach the repository root either way.
+ *
+ * Returned as a FUNCTION rather than a module constant so a test can assert on the resolution without
+ * this module's import-time filesystem state deciding it, and so the "does it exist" check below is a
+ * warning on a path that is genuinely optional rather than a startup crash on a build that skipped it.
+ */
+export declare function taskExtensionPath(from?: string): string;
+/** Bridges a Pi session to Super Pi through Pi's documented JSONL RPC protocol. */
+export declare class PiRpcRuntime implements AgentRuntime {
+    private readonly sessionDir;
+    /**
+     * Where agent definitions are read from and where their prompt bodies are written. A THIRD positional
+     * parameter rather than part of the second one, so every existing `new PiRpcRuntime(dir, launcher)`
+     * call site keeps its meaning - moving the agent directory into that slot would have silently fed a
+     * launcher's file path in as a directory of agent definitions.
+     */
+    private readonly agents;
+    /**
+     * How the `task` extension reaches this server. A FOURTH positional parameter for the same reason as
+     * the third: an options bag in one of the earlier slots would silently change what an existing
+     * `new PiRpcRuntime(dir, launcher, { dir, promptDir })` call site means.
+     *
+     * `endpoint` is this server's own listening URL, supplied rather than derived. It is the fix for
+     * hardcoding a port: `SUPER_PI_PORT` is honoured by `index.ts` and by every test that boots on
+     * `freePort()`, so an extension that dialled a fixed number would reach nothing at all. When it is
+     * absent the extension is simply not mounted, and the reason is logged once per turn rather than
+     * swallowed - a task tool that is mysteriously missing is the single hardest failure here to
+     * diagnose from the outside.
+     *
+     * `todoEndpoint` is the `todowrite` endpoint, supplied the same way and for the same reason, and it
+     * is a SEPARATE field rather than a path derived from `endpoint`: the two tools are allowed to be
+     * available independently (a harness that only exercises dispatch does not want a todo writer, and an
+     * older checkout has no todo endpoint at all), and a derived path could not tell "not configured"
+     * from "configured wrong". When it is absent the tool still registers and the extension refuses in
+     * words, which is what `refuseTodo` in core.ts is for.
+     */
+    private readonly options;
+    private readonly runs;
+    /**
+     * `steer` commands written to a child and not yet answered by Pi, keyed by the command id.
+     *
+     * A steer has to be correlated to a promise rather than fire-and-forget, because Pi's `steer` response
+     * carries a `disposition` that decides whether the message is already in the model's context or still
+     * waiting (`handled` vs `queued`, `rpc-mode.ts:416-419`). Without that answer Super Pi would have to
+     * guess, and both guesses are wrong: reporting a delivered steer as waiting would leave a message
+     * stranded in the dock forever, and reporting a waiting one as delivered would let the user cancel a
+     * message the model is about to act on.
+     */
+    private readonly pendingSteers;
+    /** Distinguishes steer command ids. Never reused, so a late response cannot settle a later steer. */
+    private steerSeq;
+    private readonly catalogs;
+    /** In-flight reads, so N clients asking at once cost ONE Pi spawn rather than N. */
+    private readonly pendingCatalogs;
+    /** Latches the "no extension on disk" warning, so it is said once rather than once per turn. */
+    private warnedMissingExtension;
+    /**
+     * Agent definitions are read from disk, never cached. A file is cheap to parse, and re-reading it
+     * per turn is the whole point: editing an agent's prompt or tool allowlist changes the NEXT message
+     * with no re-selection and no restart, which a cache would silently prevent.
+     *
+     * `command` is an override for tests and for a Pi installed somewhere unusual; with none given, Pi is
+     * resolved through `resolvePiCommand()` (override -> PATH -> npm's global bin directory), the same
+     * function scripts/probe-agent-real-pi.mjs uses. Resolved ONCE here because it is a filesystem
+     * lookup, and a resolution that could change mid-run would make a turn's spawn line depend on when
+     * it was started.
+     */
+    private readonly pi;
+    constructor(sessionDir: string, command?: string, 
+    /**
+     * Where agent definitions are read from and where their prompt bodies are written. A THIRD positional
+     * parameter rather than part of the second one, so every existing `new PiRpcRuntime(dir, launcher)`
+     * call site keeps its meaning - moving the agent directory into that slot would have silently fed a
+     * launcher's file path in as a directory of agent definitions.
+     */
+    agents?: {
+        dir: string;
+        promptDir: string;
+    }, 
+    /**
+     * How the `task` extension reaches this server. A FOURTH positional parameter for the same reason as
+     * the third: an options bag in one of the earlier slots would silently change what an existing
+     * `new PiRpcRuntime(dir, launcher, { dir, promptDir })` call site means.
+     *
+     * `endpoint` is this server's own listening URL, supplied rather than derived. It is the fix for
+     * hardcoding a port: `SUPER_PI_PORT` is honoured by `index.ts` and by every test that boots on
+     * `freePort()`, so an extension that dialled a fixed number would reach nothing at all. When it is
+     * absent the extension is simply not mounted, and the reason is logged once per turn rather than
+     * swallowed - a task tool that is mysteriously missing is the single hardest failure here to
+     * diagnose from the outside.
+     *
+     * `todoEndpoint` is the `todowrite` endpoint, supplied the same way and for the same reason, and it
+     * is a SEPARATE field rather than a path derived from `endpoint`: the two tools are allowed to be
+     * available independently (a harness that only exercises dispatch does not want a todo writer, and an
+     * older checkout has no todo endpoint at all), and a derived path could not tell "not configured"
+     * from "configured wrong". When it is absent the tool still registers and the extension refuses in
+     * words, which is what `refuseTodo` in core.ts is for.
+     */
+    options?: {
+        endpoint?: string;
+        todoEndpoint?: string;
+        uploadsDir?: string;
+    });
+    /**
+     * The agent a conversation runs as, or undefined for Pi's own defaults.
+     *
+     * A missing file is NOT an error: a conversation that names an agent that has since been deleted
+     * degrades to running as Pi itself, with a warning, rather than failing every turn forever. A
+     * `subagent` definition is also ignored here - those are invoked BY a primary agent, never chosen
+     * as the conversation's own role.
+     */
+    agentFor(conversation: Pick<Conversation, "id" | "agentId">): Promise<AgentDefinition | undefined>;
+    /**
+     * The `--extension` argv for this turn, or `[]` when the task tool is not available.
+     *
+     * Empty in TWO different situations, and both are deliberate rather than merged:
+     *
+     * - No endpoint was configured, so there is nowhere for the extension to dispatch to. Mounting it
+     *   anyway would give the model a tool whose every call fails with a network error.
+     * - The extension file is not on disk. That is a build or checkout problem, and it is warned about
+     *   ONCE rather than every turn, because "your primary agent cannot delegate anything" is worth
+     *   knowing and worth not repeating on every keystroke.
+     */
+    private taskExtensionArgs;
+    /**
+     * The five values the extension reads out of its own environment. See `task-tool.ts` for why they are
+     * written out on both sides rather than imported.
+     *
+     * The ROSTER is read here, per turn, from the same `readAgents` the picker and the supervisor use -
+     * never from a list written into this file. A sub-agent added while the server is running is therefore
+     * dispatchable on the next message with no restart, which is the same freshness rule `agentFor`
+     * follows for agent files and for the same reason: a human edits those files while the server runs.
+     *
+     * `depth` is `0`, hardcoded, and that is not an oversight: this is the PRIMARY agent's spawn, so it is
+     * definitionally at the top of the tree. `SubagentSupervisor` never passes this function, which is why
+     * no sub-agent process is ever given this environment at all.
+     *
+     * The TODO ENDPOINT is the one value here that is NOT per-turn derived from disk: it is this server's
+     * own address, so it is the same string on every turn and is read once from the constructor's options.
+     */
+    private taskExtensionEnv;
+    answer({ conversation, prompt, signal, cwd, host, onPiQueue, onUserEntry, onToolCall, onToolEnd, images }: AnswerInput): AsyncIterable<string>;
+    /**
+     * Reads back the id of the user message this turn just created, and hands it to the caller.
+     *
+     * `head` is the already-answered pre-turn `get_entries`, whose `leafId` is what makes the second read
+     * exact. Its three possible outcomes are handled differently ON PURPOSE, because they mean different
+     * things and two of them must not produce an id:
+     *
+     * - `leafId: null` - the session was empty, so this IS the first turn and the whole entry list is this
+     *   turn's. Safe to take the first user message from it.
+     * - `leafId: "..."` - read only what came after it. Safe, and the only correct answer for turn two onward.
+     * - no usable answer - Pi never told us where the turn began, so NOTHING in the transcript can be
+     *   attributed to it. Reading everything and taking "the first user message" here would hand back a
+     *   PREVIOUS turn's id, and a revert to that id would silently cut more than the user asked for. So this
+     *   case records nothing and says why.
+     *
+     * Every failure is a warning, never a throw: the turn's answer has already streamed by this point, and
+     * "this message cannot be a revert boundary" is not "your message failed".
+     */
+    private recordTurnEntryId;
+    /**
+     * Reverts Pi's own transcript to the state right after `boundaryEntryId`.
+     *
+     * ============================ WHAT THIS DESTROYS ============================
+     * Every Pi entry after that boundary, permanently - including tool calls, compaction records, model and
+     * thinking-level markers, and usage accounting, not just the messages Super Pi shows. A copy of the file
+     * as it was is left beside it as `<file>.super-pi-revert-backup`, which Pi never lists because it does
+     * not end in `.jsonl`. There is no undo in the application.
+     *
+     * No workspace file is read, written or restored. That is the whole point of not reaching for OpenCode's
+     * `snapshot/` machinery: its revert rolls the working tree back (`snapshot/index.ts:382-406`), this one
+     * must not, and Super Pi has no reason to build a second git shadow repository to do damage.
+     * =============================================================================
+     *
+     * WHY PI IS ASKED WHICH FILE TO OPEN, rather than this code scanning the session directory.
+     *
+     * The obvious implementation - read the directory, find the `*.jsonl` whose header id matches - is
+     * exactly the one that fails silently, and probe B measured why:
+     *
+     * 1. When Pi cannot find the requested id it does NOT fail. It prints a warning to stderr and opens a
+     *    brand-new session under that same id (`main.ts:436-448`), so a wrong lookup becomes "the history
+     *    has vanished" with no error anywhere in the UI. Measured:
+     *    `Warning: No project session found with id '...'; creating a new session with that id.`
+     * 2. Pi's lookup is not "match the id". With an explicit `--session-dir` it ALSO requires the session's
+     *    recorded `cwd` to equal the one it was asked from (`session-manager.ts:1874-1891`), and probe B
+     *    measured the same id resolving to two different files from two different working directories -
+     *    one of which did not exist on disk.
+     *
+     * So the file is taken from Pi's own `get_state.sessionFile` (`rpc-mode.ts:448-464`), which is the
+     * lookup Pi performed for a real spawn, and then THREE things are checked before a byte is written:
+     * the file exists, its header is the session header, and that header's id is the conversation being
+     * reverted. A miss on any of them refuses, in words, rather than truncating something it is not sure of.
+     *
+     * The cost is one extra Pi spawn, which is why this is a deliberate trade rather than an oversight:
+     * revert is a rare, deliberate act, and a second Pi answers in well under a second. It buys the
+     * elimination of an entire class of "we truncated the wrong file and nothing said so" failures.
+     */
+    revert({ conversation, cwd, boundaryEntryId }: RevertRequest): Promise<RevertOutcome>;
+    /**
+     * Copies Pi's own transcript for one conversation into a second, independent file under a new id.
+     *
+     * THE SAME THREE STEPS AS REVERT, IN THE SAME ORDER, AND FOR THE SAME REASONS: refuse a live turn, ask Pi
+     * which file it uses rather than scanning the directory (probe B measured that a directory scan resolves
+     * the wrong file or a nonexistent one with no error, and that Pi invents an empty session under an id it
+     * cannot find), kill that Pi BEFORE touching anything on disk, and check the file's header against the
+     * conversation being forked before a byte is written. Every one of those paragraphs above still applies
+     * here word for word, because it is the same machinery pointed the other way: revert cuts a file in
+     * place, fork copies a file beside it.
+     *
+     * ============================ WHAT A FORK COPIES ============================
+     * The file, byte for byte, with two header fields changed (`id`, `parentSession` - see `forkSessionFile`).
+     * Entry ids are NOT renumbered, so every message recorded on the source keeps a `piEntryId` that is valid
+     * in the fork too, which is what keeps REVERT working inside a forked conversation.
+     * =============================================================================
+     *
+     * WHAT A FORK DOES NOT COPY, and both omissions are deliberate:
+     *
+     * - **Sub-agent runs.** `SubagentRun.conversationId` points at the conversation that dispatched it, and
+     *   research pitfall 7 is that truncating or duplicating a transcript leaves those records orphaned. A
+     *   forked conversation shows the messages but no child cards from before the fork: the children belong to
+     *   the conversation that started them, they are not listed anywhere once their parent has copied their
+     *   words, and a card in the fork that could not be stopped from the fork would be worse than no card.
+     * - **Queued messages.** Same argument, and narrower: a waiting message belongs to the run in progress,
+     *   and a run is not copied.
+     *
+     * THE EMPTY-CONVERSATION CASE IS NOT AN ERROR. A conversation with no messages has no Pi file at all -
+     * `SessionManager._persist` only creates one once a session holds a message (`:1160-1170`) - so there is
+     * nothing to copy and the fork is a copy of `state.json` alone. That is checked BEFORE any Pi is spawned,
+     * so forking a fresh conversation costs nothing and cannot fail. The converse is refused rather than
+     * tolerated: messages in `state.json` with no Pi file means the two histories were ALREADY out of step,
+     * and copying that into a second conversation would make the disagreement permanent and multiply it.
+     */
+    fork({ conversation, cwd, forkedConversationId }: ForkRequest): Promise<ForkOutcome>;
+    /**
+     * Delivers one Extension UI request. One-way methods are pushed to the host and never replied to
+     * (Pi holds no pending entry, so a response would resolve nothing). Blocking methods are handed to
+     * the host and this call is awaited, so Pi stays blocked exactly as long as the human takes.
+     */
+    private handleExtensionUi;
+    stop(conversationId: string): Promise<void>;
+    /**
+     * Injects one message into the Pi process that is running right now, at its next turn boundary.
+     *
+     * `steer` and NOT `follow_up`, and NOT `prompt` with a `streamingBehavior`. The three are not
+     * interchangeable and the difference is the whole feature:
+     *
+     * - `steer` is drained at `agent-loop.ts:295`, after `turn_end` and therefore after the current
+     *   assistant message's WHOLE tool-call batch has finished, before the next LLM request. The agent
+     *   stops doing what it was doing at the next boundary instead of at the end of the task. That is
+     *   "插队", and its granularity is a tool BATCH - a long single tool call is not interruptible,
+     *   because Pi offers no preemption.
+     * - `follow_up` is drained at `agent-loop.ts:302`, only once the agent has stopped on its own.
+     * - `prompt` would start a turn, which is the thing that must NOT happen here: this conversation
+     *   already has a turn in flight, and starting a second one is the two-writers-one-session bug.
+     *
+     * NO `set_follow_up_mode` / `set_steering_mode` IS EVER SENT, and that is a hard rule rather than a
+     * default. Both go through `AgentSession.set*Mode`, which mutates `SettingsManager`'s global scope and
+     * calls `save()` (`settings-manager.ts:857-871`), writing to the user's Pi `settings.json`. A host that
+     * merely wanted a different queue depth would permanently rewrite the user's Pi configuration. Pi's
+     * default is already `one-at-a-time` (`agent.ts:247-248`), which is the semantics this wants: one
+     * queued message consumed per boundary.
+     *
+     * REJECTS rather than reporting success when there is no live child, and when Pi does not answer in
+     * time. The caller keeps the message cancellable in the first case because it provably reached no
+     * model; in the second the outcome is genuinely unknown and a `sending` state says so.
+     */
+    steer(conversationId: string, message: string, images?: MessageImage[]): Promise<SteerDisposition>;
+    /**
+     * The model/thinking catalog, from Pi, cached.
+     *
+     * Three layers, because a picker opens far more often than Pi can be asked: a TTL cache keyed by
+     * the selection (10 minutes for a good answer, 30 seconds for a failure), an in-flight map so
+     * concurrent callers share one spawn, and - because each read spawns a short-lived Pi that is
+     * killed as soon as it has answered - no long-lived process to keep warm.
+     */
+    catalog(selection?: ModelSelection): Promise<ModelCatalog>;
+    /**
+     * Asks one throwaway Pi for its model list, its thinking levels and its own current selection.
+     *
+     * The three commands are written back to back and only then awaited, so Pi works on them in
+     * parallel - measured at 394ms for all three, against 714ms for the slowest one alone. A Pi
+     * scoped to one conversation's model needs `set_model` FIRST and alone, because thinking levels are
+     * a property of the selected model, not of Pi's default.
+     */
+    private readCatalog;
+}
+/**
+ * Normalizes Pi's `Model[]`, keeping only entries that can actually be sent back as a `set_model`.
+ * Exported so the mapping is testable without a Pi process.
+ *
+ * `imageInput` reads Pi's `input` array, which is where image support is actually declared -
+ * `BaseModel.input: ("text" | "image")[]` at packages/ai/src/types.ts:1124, and Pi's own CLI prints
+ * the very same test as its "images" column (cli/list-models.ts:71, `m.input.includes("image")`).
+ * Copying Pi's predicate rather than inventing one is the point: if Pi ever renames the value or
+ * adds a third modality, Pi's column and this badge change together.
+ *
+ * A MISSING OR MALFORMED `input` READS AS FALSE, and that direction is deliberate. The field's
+ * failure mode is a silent one in both directions - Pi's RPC reader does no schema validation
+ * (rpc-mode.ts:750-783) - so a model with no `input` at all could be a Pi too old to have the
+ * concept, and answering "supports images" for it would invite a picture the model cannot see.
+ * Announcing a capability that turns out to be absent costs the user a confusing turn; declining to
+ * announce one that is present costs them an unlabelled model. Only the first is worth guessing on.
+ */
+export declare function describeModel(value: unknown): ModelOption | undefined;
+export declare function describeModels(value: unknown): ModelOption[];