@evandu/super-pi 0.0.0-stage → 0.1.1

package/dist/server/types.d.ts

@@ -0,0 +1,920 @@
+export type RunStatus = "idle" | "running" | "completed" | "stopped" | "failed";
+export type MessageRole = "user" | "assistant" | "tool" | "system";
+/**
+ * One message in `state.json`.
+ *
+ * `piEntryId` is Pi's own id for the entry this message became, recorded while Pi was still alive.
+ *
+ * WHY A SUPER Pi MESSAGE NEEDS A PI ID AT ALL. The two histories are separate files in separate formats
+ * - `state.json` here, Pi's session JSONL in the session directory - and they share nothing but the
+ * conversation id (research §3.2). A revert has to cut BOTH at the same place, and Pi's file can only be
+ * cut at one of its own entry ids: `SessionManager` refuses to delete entries (`:1516-1519`), and the
+ * research' pitfall 6 rules out guessing a line number, because Pi writes far more entry types than
+ * messages and a "the Nth user message" boundary would slice a compaction record in half.
+ *
+ * So the id is captured per turn, from Pi's own `get_entries` (`rpc-mode.ts:636-647`), in the only window
+ * where it is available: Super Pi spawns one Pi per turn and kills it in a `finally`
+ * (`runtime.ts:429-435`), so the answer has to be taken before that. A message recorded before this
+ * field existed has no id, and is therefore not a valid revert boundary - which the handler says out
+ * loud rather than reverting to a guessed line.
+ *
+ * Optional on purpose: a `state.json` written before revert existed has no such key, and absent reads as
+ * "Pi never told us", needing no migration.
+ *
+ * `toolCalls` is the OTHER optional field, and it lives ON THE MESSAGE rather than in a separate top-level
+ * array. That is a claim about where a call happens: Pi executes a tool call after the assistant message
+ * that requested it and before the next one, so the calls belong to the turn the message belongs to and to
+ * nothing else. Attaching them there makes the transcript's ordering free - a block renders under its own
+ * message, and a reload rebuilds it from the same `state` snapshot the text came from, with no second source
+ * of truth to fall out of sync.
+ *
+ * A FOLLOW-UP ROUND GETS ITS OWN, because each one calls `beginAssistantMessage` and therefore opens a
+ * fresh message: the chain in `index.ts` sends a queued message as a new prompt, and Pi's calls for that
+ * prompt cannot be filed under the answer to the previous one.
+ *
+ * Also optional, so a `state.json` written before either field existed reads as "this turn used no tools",
+ * which is what such a turn genuinely is.
+ */
+/**
+ * One image attached to a message or queue item.
+ * Stored as a reference (file ID + metadata), NEVER base64 bytes in state.json,
+ * to prevent massive state bloat during streaming broadcast.
+ */
+export type MessageImage = {
+    id: string;
+    name?: string;
+    mimeType: string;
+    bytes: number;
+    width?: number;
+    height?: number;
+};
+export type Message = {
+    id: string;
+    role: MessageRole;
+    content: string;
+    createdAt: string;
+    piEntryId?: string;
+    toolCalls?: ToolCallBlock[];
+    images?: MessageImage[];
+};
+/**
+ * ONE PARAMETER OF A TOOL CALL, as a call block lists it, and the boundary that keeps Pi's arguments out
+ * of `state.json`.
+ *
+ * `value` is DERIVED, never the raw argument: a string is whitespace-collapsed and hard-capped, and
+ * anything that is not a string, a number or a boolean becomes a bare type word (`（对象）`,
+ * `（数组 3 项）`). That second half is the load-bearing part - an `edit`'s arguments routinely carry a
+ * replacement block for a whole file, so rendering such a value even truncated would put file contents
+ * into a field that is persisted in `state.json` and broadcast to every browser. See `describeToolCallArgs`.
+ */
+export type ToolCallArg = {
+    key: string;
+    value: string;
+};
+/**
+ * ONE TOOL CALL THE PRIMARY AGENT MADE, as a block in the transcript.
+ *
+ * SAME FOUR FACTS AS `SubagentToolCall`, and deliberately the same granularity: `label` is the tool name,
+ * `detail` is the one bounded line naming what it was aimed at (the file it read, the pattern it searched
+ * for, the command it ran), `status` and `durationMs` come from Pi's own `tool_execution_end`. A call block
+ * that showed MORE than a sub-agent card row would answer a question the brief does not ask and would make
+ * the two surfaces disagree about what a tool call is.
+ *
+ * `args` is the ONE addition, and it is what makes a block worth expanding: a card row answers "what was
+ * this aimed at", while a block also answers "what else was it given" - a `bash` call's timeout, a
+ * `read`'s offset. Bounded to six entries of capped text by `TOOL_ARG_CAP`, so this stays a summary
+ * rather than becoming the transcript.
+ *
+ * TWO THINGS ARE NOT HERE AND NEVER WILL BE. `result` on `tool_execution_end` is, for a `read`, the file's
+ * contents; and Pi's `toolCallId` is an identity only Pi can resolve, which is why the record is addressed
+ * by position (the caller holds a `toolCallId` → row map for the length of a turn, exactly as
+ * `SubagentRunRecorder` does) rather than by a field persisted forever.
+ *
+ * `status` is OPTIONAL, not defaulted to `"ok"`, for the same reason it is on `SubagentToolCall`: a default
+ * would claim an outcome nobody observed. Absent means the call is still in flight, which is the state a
+ * block is in for most of a long tool call.
+ */
+export type ToolCallBlock = {
+    label: string;
+    detail?: string;
+    status?: "ok" | "error";
+    durationMs?: number;
+    args?: ToolCallArg[];
+};
+/**
+ * WHAT THE RUNTIME HANDS A CALLER WHEN PI ANNOUNCES OR FINISHES A TOOL CALL.
+ *
+ * Mirrors `SubagentToolCall` and is declared here rather than in `runtime.ts` because `runtime.ts` cannot
+ * import `subagents.ts` (that module imports the runtime), so a type living beside the supervisor would be
+ * unreachable from the only file that produces the primary agent's calls. It carries Pi's `id` because the
+ * CALLER needs it to match an end back to its start - the persisted `ToolCallBlock` deliberately does not.
+ */
+export type ToolCallNotice = {
+    id: string;
+    name: string;
+    detail?: string;
+    args?: ToolCallArg[];
+    status?: "ok" | "error";
+    durationMs?: number;
+};
+/**
+ * `archivedAt` is the whole archive mechanism: a state MARKER, not a move. The conversation object never
+ * changes workspace or position, so archiving and restoring are a stamp and a clear of one optional field.
+ *
+ * It is optional on purpose. A `state.json` written before archiving existed simply has no such key, so
+ * `undefined` means "not archived" and old state loads as live with no migration step and no data rewrite.
+ * An ISO-8601 string also carries when the conversation was archived, which the sidebar shows in place of
+ * the live timestamp.
+ */
+/**
+ * The model a conversation runs on. Provider and id are ONE optional field, never two, because Pi's
+ * `set_model` command takes both (rpc-mode.ts:470) and a half-updated pair - an id without its
+ * provider, or a provider whose id no longer exists - is a selection Pi rejects at the start of the
+ * next turn. Nesting them makes that state unrepresentable.
+ *
+ * `label` is the display name Pi itself reported, kept so a conversation opened without a catalog
+ * fetch still renders something a human recognises instead of a bare model id.
+ */
+export type ModelSelection = {
+    provider: string;
+    modelId: string;
+    label: string;
+};
+/**
+ * One entry of Pi's `get_available_models` answer, narrowed to what a picker needs. Pi's `Model`
+ * objects also carry baseUrl, cost tables and compat maps (17KB for the 28 models this build sees);
+ * keeping them would put provider URLs in the browser's state for no gain. `detail` is
+ * `provider/modelId`, the pair Pi needs back in `set_model`, shown so two same-named models from
+ * different providers are distinguishable.
+ *
+ * `imageInput` is derived from Pi's own `input` array rather than carried raw, so the browser holds
+ * one boolean instead of a modality list it would have to interpret. It is CATALOG state, never
+ * conversation state: a copy frozen onto a conversation would be wrong the moment Pi changed a
+ * model, and nothing reads one - see the note on `setConversationModel`.
+ */
+export type ModelOption = ModelSelection & {
+    detail: string;
+    reasoning: boolean;
+    contextWindow: number;
+    imageInput: boolean;
+};
+/**
+ * What the picker lists, read from Pi and cached by the runtime.
+ *
+ * `source` is "unavailable" when Pi could not be asked, which the UI renders as a disabled control
+ * rather than an empty list: an empty list is indistinguishable from "you have no models", and the
+ * honest answer is "the list could not be read". `fetchedAt` travels with the value so a stale
+ * cache is visible rather than silent.
+ */
+export type ModelCatalog = {
+    source: "pi" | "unavailable";
+    models: ModelOption[];
+    /** Exactly what `get_available_thinking_levels` returned, in Pi's own order. Never hardcoded. */
+    levels: string[];
+    defaultModel?: ModelSelection;
+    defaultThinkingLevel?: string;
+    fetchedAt: string;
+    error?: string;
+};
+export type Conversation = {
+    id: string;
+    title: string;
+    workspaceId: string;
+    updatedAt: string;
+    status: RunStatus;
+    messages: Message[];
+    archivedAt?: string;
+    /**
+     * Why this conversation is not `running`, in WORDS A PERSON READS - the same role `SubagentRun.error`
+     * plays for a card, one level up.
+     *
+     * Set by startup reconciliation, and ONLY by it: a conversation the previous server left `running` is
+     * failed here with this reason, and `addUserMessage` deletes the key the moment the user retries, so
+     * the field can never describe a run other than the one that most recently failed to finish. A value
+     * that outlived its run would be worse than no value at all, because the reader would take it for the
+     * current turn's outcome.
+     *
+     * Prose rather than a code because this is the ONE string from state.json that a human is expected to
+     * read on purpose; the chat pane renders it verbatim under the header. An internal error code here
+     * would answer "what happened" with something the reader has to go and decode.
+     */
+    error?: string;
+    /** Absent means "Pi's own default", which is why a conversation created before the picker existed still works. */
+    model?: ModelSelection;
+    thinkingLevel?: string;
+    /**
+     * The agent whose role, tool allowlist and prompt apply to this conversation's turns. Absent means
+     * "Pi's own defaults", exactly as for `model` - so a state.json written before agents existed needs
+     * no migration and reads as a conversation with no role.
+     *
+     * It holds only the ID, never a copy of the agent. The definition is re-read from disk on every turn,
+     * so editing an agent's prompt or tools takes effect on the next message with no re-selection, and a
+     * deleted agent degrades to "no role" instead of leaving a stale snapshot in state.json.
+     */
+    agentId?: string;
+};
+/**
+ * One parsed agent definition, as read from an `agents/*.md` file. `prompt` is the file body and is the
+ * system prompt; the frontmatter fields are borrowed from OpenCode's agent format.
+ *
+ * `toolFlags` is the TRANSLATED Pi command line, not the raw map: `tools: {"*": false, read: true}`
+ * becomes `["--tools", "read"]`. Keeping the translation next to the definition means the runtime
+ * cannot pick a different one, and a test can assert the exact flags without spawning Pi.
+ */
+export type AgentDefinition = {
+    /** The file's base name. Stable, human-chosen, and the id a conversation stores. */
+    id: string;
+    name: string;
+    mode: "primary" | "subagent";
+    description: string;
+    color?: string;
+    hidden: boolean;
+    /** `provider/modelId` from frontmatter, split into the pair Pi's `set_model` requires. */
+    model?: {
+        provider: string;
+        modelId: string;
+    };
+    thinkingLevel?: string;
+    /** `append` adds the body to Pi's baseline prompt; `replace` makes it the whole system prompt. */
+    promptMode: "append" | "replace";
+    toolFlags: string[];
+    taskPolicy?: Record<string, unknown>;
+    /** For display only. Empty means "Pi's own default tool set" or "every tool denied". */
+    toolNames: string[];
+    /**
+     * The `tools:` frontmatter MAP, kept alongside the flags it was translated into.
+     *
+     * `toolFlags` is the answer to "what does Pi get"; this is the question behind it. Keeping the source
+     * next to the translation is what lets a caller's constraint be applied to an agent that is about to be
+     * spawned - a child whose allowlist must lose the tools its parent denied
+     * (`agentSpawnArgs(..., { denyTools })`) cannot be expressed by editing a flag list that has already
+     * been flattened into two argv strings. Kept optional so a hand-built definition in a test does not
+     * have to invent one.
+     */
+    tools?: Record<string, unknown>;
+    prompt: string;
+};
+/**
+ * What the picker receives. The prompt body is deliberately NOT sent: it is a whole system prompt,
+ * the browser has no use for it, and state.json plus the agent catalog stay small.
+ */
+export type AgentSummary = Omit<AgentDefinition, "prompt" | "toolFlags" | "tools"> & {
+    toolSummary: string;
+};
+export type AgentCatalog = {
+    source: "directory" | "unavailable";
+    agents: AgentSummary[];
+    /** Files that exist but are not usable agents, so a typo is visible instead of silently absent. */
+    problems: {
+        file: string;
+        message: string;
+    }[];
+    directory: string;
+    fetchedAt: string;
+    error?: string;
+};
+/**
+ * Workspace-level DEFAULTS for conversations not yet created. Both fields are optional for the same
+ * reason Conversation's are: a state.json written before workspace settings existed has no such keys,
+ * and absent means "Pi's own default" with no migration step.
+ *
+ * These are copied INTO a conversation at creation time (store.createConversation) and never read
+ * afterwards. That copy is the whole "default vs override" semantics: the session picker's value is
+ * the conversation's own field, an existing conversation is therefore immune to later workspace
+ * edits, and deleting the workspace default cannot reach back into sessions already born.
+ */
+export type Workspace = {
+    id: string;
+    name: string;
+    path: string;
+    updatedAt: string;
+    defaultModel?: ModelSelection;
+    defaultThinkingLevel?: string;
+    defaultAgentId?: string;
+};
+/**
+ * Usage accumulated across one sub-agent run. `turns` is the number of finished assistant messages,
+ * not a token total: it is what tells a human whether a sub-agent did one pass or twenty.
+ *
+ * Declared HERE rather than in `subagents.ts` because this is a persisted shape - it is copied into
+ * `state.json` and back out - and a type that lives next to the code that produced it cannot be
+ * checked by the one that consumes it.
+ */
+export type SubagentUsage = {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+    turns: number;
+};
+/**
+ * ONE TOOL CALL, as the card shows it, and the boundary that keeps a child's turn out of `state.json`.
+ *
+ * `detail` is a SHORT LABEL of what the call was aimed at - the file it read, the pattern it searched
+ * for, the command it ran - and it is the only part of the child's arguments Super Pi keeps. That is a
+ * deliberate line, not an oversight, and it is drawn in three places at once:
+ *
+ * 1. **It is derived, never copied.** `describeToolCall` reads named argument fields and renders ONE
+ *    capped line; the argument object itself is dropped. A `read` whose result is a whole file still
+ *    contributes nothing but its path.
+ * 2. **It is bounded.** 120 characters, whitespace collapsed, no newlines - so the label cannot grow
+ *    into a transcript, and a `state.json` serialized on every broadcast stays small by construction
+ *    rather than by hope.
+ * 3. **The RESULT never lands here at all.** `tool_execution_end` carries `result`, which for a `read`
+ *    is the file's contents; only its `isError` and its `durationMs` are kept, because both are
+ *    numbers rather than text. This is the guard `scripts/agent-vis-records.test.mjs` pins down.
+ *
+ * `status` is OPTIONAL rather than defaulted to `"ok"` for a reason that is now historical: when this
+ * type was declared, the protocol surface announced tools and never reported how they ended, so a
+ * default would have claimed an outcome nobody observed. Pi does send `tool_execution_end`, the
+ * supervisor consumes it, and a call that has not ended yet still has no `status` - which is exactly
+ * what makes an in-flight row distinguishable from a finished one.
+ *
+ * `durationMs` is Pi's own measurement off a monotonic clock, not this project's clock, and it is the
+ * one outcome number that is true for EVERY tool rather than only the shapes this code recognises.
+ */
+export type SubagentToolCall = {
+    label: string;
+    status?: "ok" | "error";
+    detail?: string;
+    durationMs?: number;
+};
+/**
+ * WHAT THE CHILD WAS DOING AT THE MOMENT THE BROWSER LAST HEARD FROM IT.
+ *
+ * A run that spends its whole life inside one long tool call emits no `text_delta`, so without this the
+ * card freezes mid-run and a frozen card is indistinguishable from a dead one. `kind` is a WORD rather
+ * than a colour, because "is it still working?" has to be answerable by someone who cannot see the
+ * green tint. `at` lets the card say how stale this is, which is the difference between "working" and
+ * "stopped answering without saying so".
+ *
+ * Optional on purpose, and cleared rather than left stale at the settle: on a finished run the last
+ * thing the child did is history, and a card that kept claiming to be 正在调用 read after the run
+ * ended would be lying.
+ */
+export type SubagentActivity = {
+    kind: "thinking" | "tool";
+    label?: string;
+    at: string;
+};
+/**
+ * WHICH PHASE A RUN DIED IN, so a failure card answers 「卡在哪」 and not only 「错了」.
+ *
+ * `error` already says what went wrong and is the older, better field; this says where. A model that
+ * cannot open its output file and one that crashed two tool calls in are both 「失败」 without it, and
+ * those have completely different fixes. Five phases, because those are the five the supervisor can
+ * actually observe - it changes this value as the drain loop meets each record family, so it cannot
+ * claim a phase it never saw.
+ *
+ * Absent means "the failure was not observed while the run was in flight" - an orphan reconciled at the
+ * next startup, for instance, whose process was gone before anything could report a phase. Inventing
+ * one there would be the exact lie this type exists to prevent.
+ */
+export type SubagentFailure = {
+    stage: "dispatch" | "prompt" | "turn" | "tool" | "settle";
+};
+/**
+ * `SubagentRun`'s lifecycle, which is NOT `RunStatus`: there is no "idle", because a run exists only
+ * between its dispatch and its settle. `stopped` is separate from `failed` for the same reason
+ * `RunStatus` keeps them apart - "the user pressed stop" and "the child broke" are different facts
+ * for whoever reads the record later, and collapsing them forces that decision back out of message
+ * matching. A fourth value is deliberately absent: a run cannot be cancelled while it has not started.
+ */
+export type SubagentRunStatus = "running" | "completed" | "failed" | "stopped";
+/**
+ * One sub-agent run, exactly as [docs/SUBAGENT-DESIGN.md](../../docs/SUBAGENT-DESIGN.md) §5 fixes it.
+ *
+ * THE RECORD, NEVER THE TRANSCRIPT. `state.json` is serialized on every broadcast and cloned into the
+ * browser on every snapshot, so a sub-agent's full conversation - arbitrarily long, and belonging to a
+ * different process with its own context window - must not go in here. What goes in is the LAST
+ * ASSISTANT MESSAGE (`output`), which is also what the parent model is told, and nothing else about the
+ * child's turn. Pi keeps the real transcript in its own `--session-dir`, and `sessionId` is the handle
+ * that gets it back (`switch_session`, or `export_html`): Super Pi records where the child's words are
+ * rather than copying them.
+ *
+ * `outputTruncated` exists because `output` may be cut: the 50 KB cap in §6 applies to the MODEL's copy
+ * only, since a human reading a sub-agent is debugging it and does not want it trimmed to fit somebody
+ * else's context window. So the browser gets the whole thing through `subagent.event` while the flag
+ * says the stored copy is less.
+ */
+export type SubagentRun = {
+    /** `sub_<uuid>`. Also Pi's `--session-id`, which is why the two are one value today. */
+    id: string;
+    /** The conversation that dispatched this run, so its card can live under the right message. */
+    conversationId: string;
+    /** The `agents/*.md` file's base name - the `mode: subagent` definition that was run. */
+    agentId: string;
+    /** What the child was asked to do, as Super Pi sent it. The dispatcher's own text, not the child's reply. */
+    task: string;
+    /**
+     * Who decided to run this: a person pressed the dispatch button, or the primary agent called the
+     * `task` tool on its own. The two are indistinguishable on the record otherwise - same agent, same
+     * task, same card - so the browser would show a model's own decision as if a person had asked for it.
+     * Absent means `human`, which is what every record written before this field existed was.
+     */
+    dispatchedBy?: "human" | "model";
+    /** Authoritative dispatch ancestry, assigned by the server. */
+    parentRunId?: string;
+    depth: number;
+    loopId?: string;
+    /** Optional orchestration label; interpretation belongs to the workflow, not the dispatcher. */
+    role?: string;
+    status: SubagentRunStatus;
+    startedAt: string;
+    finishedAt?: string;
+    /** The last assistant message. Absent while running is only for a run that has produced none yet. */
+    output?: string;
+    /**
+     * Every tool the child started, oldest first, appended as the run streams. Same rule as `output`:
+     * short labels go here and to the card, the child's full turn stays in Pi's session directory.
+     *
+     * Optional on purpose. It was added to the design AFTER part 2 shipped, so a `state.json` written
+     * by an older build has no such key and an absent one reads as "this child used no tools", which is
+     * what a run with none genuinely means.
+     */
+    toolCalls?: SubagentToolCall[];
+    /** True when `output` was cut for the model's benefit; the browser still saw all of it. */
+    outputTruncated?: boolean;
+    usage?: SubagentUsage;
+    error?: string;
+    /**
+     * How long the run took, measured by THIS server between writing the `running` row and settling it.
+     *
+     * Added because of a measurement, not a preference: a real sub-agent reading three files finished in
+     * 2.5 seconds, so a user glancing at the transcript afterwards could not tell whether the card had
+     * ever been anything but 已完成. A run that leaves a DURATION behind turns "I never saw it run" into
+     * "it ran for 2.5s", which is a fact, and it is the fact that makes the invisible run observable
+     * after the fact rather than only during a window nobody was looking at.
+     *
+     * Written at the settle only. While the card is live the elapsed time is the browser's own arithmetic
+     * on `startedAt`, so a client clock that disagrees with this one cannot change what was recorded.
+     */
+    durationMs?: number;
+    /** What the child was doing last. Live only: absent once the run has settled. */
+    activity?: SubagentActivity;
+    /** Which phase it died in. Absent on a run that finished normally, and on an unreconciled orphan. */
+    failure?: SubagentFailure;
+    /** Pi's own session id for the child. Its transcript lives there and is never parsed by Super Pi. */
+    sessionId: string;
+};
+/**
+ * What may change on a run that has already been recorded.
+ *
+ * A named list rather than `Partial<SubagentRun>` because the fields a run must NEVER change are the
+ * point: `id` is the key startup reconciliation looks orphans up by, and `conversationId`/`agentId`/
+ * `task`/`startedAt` are the facts the run was DISPATCHED with. A patch that could rewrite any of them
+ * could produce a record whose id matches nothing that ran - unreconcilable, and unattributable.
+ * `sessionId` is the one identity field allowed to move, and only because a run's id and Pi's session id
+ * happen to coincide today rather than by definition.
+ */
+export type SubagentRunUpdate = Partial<Pick<SubagentRun, "status" | "output" | "outputTruncated" | "toolCalls" | "usage" | "error" | "finishedAt" | "sessionId" | "durationMs" | "activity" | "failure">>;
+export type BackgroundTaskSummary = {
+    id: string;
+    title: string;
+    agentId: string;
+    status: "running" | "completed" | "failed";
+    startedAt: string;
+    resultBlockId: string;
+};
+export type AppState = {
+    workspaces: Workspace[];
+    conversations: Conversation[];
+    subagentRuns: SubagentRun[];
+    queuedMessages: QueuedMessage[];
+    backgroundTasks: BackgroundTaskSummary[];
+    todos?: TodoItem[];
+};
+export type TodoItem = {
+    id?: string;
+    content: string;
+    status: "pending" | "in_progress" | "completed";
+    priority?: "high" | "medium" | "low";
+};
+/**
+ * One message the user sent WHILE THE AGENT WAS WORKING, held by Super Pi until a turn boundary can
+ * carry it.
+ *
+ * WHY THE SERVER OWNS THIS LIST AT ALL. Pi's own queues live in the Pi process's memory
+ * (`agent-session.ts:394/396`) and Super Pi kills that process unconditionally at the end of every
+ * turn (`runtime.ts:539-545`), while Pi never writes a queued message to the session JSONL. A list kept
+ * in Pi is therefore guaranteed to be destroyed, with no trace, on every turn boundary. So Pi is used
+ * only as a delivery pipe - one steer per turn, handed over at the moment it is allowed to be
+ * delivered - and the waiting list is this one.
+ *
+ * THE ID IS OURS AND IT IS THE POINT. Pi matches a queued message back to its queue entry by
+ * `indexOf` on the message TEXT (`agent-session.ts:1123/1129`), so two queued messages with identical
+ * text are indistinguishable to it and one of them is left behind in its queue forever. Every entry
+ * here therefore carries a Super Pi id that Pi never sees, and cancel/steer address THAT.
+ *
+ * `state` is the whole lifecycle, and `sending` is the only irreversible step:
+ *
+ * - `queued`  - in the list, not yet given to Pi. CANCELLED freely; this is where essentially every
+ *               message lives, because a message is only handed to Pi when it is about to be delivered.
+ * - `sending` - written to Pi's stdin as a `steer` and not yet confirmed delivered. NOT cancellable:
+ *               Pi has no single-item retract (its only queue command is `clear_queue`, which clears
+ *               everything), so claiming otherwise in the UI would be a lie. It goes back to `queued`
+ *               exactly when we can prove Pi never delivered it - the turn ended - and stays here when
+ *               Pi simply has not answered yet.
+ *
+ * A delivered or cancelled message is REMOVED rather than kept with a terminal state: a queue that
+ * retains sent messages needs a pruning policy and a way to read it, and a stale row in this list is
+ * worse than no row.
+ */
+export type QueuedMessage = {
+    /** `q_<uuid>`. Super Pi's own identity for this message, and the only thing cancel/steer name. */
+    id: string;
+    /**
+     * The conversation whose next turn will carry this. Deliberately a CONVERSATION id and never a
+     * `sub_*` run id: sub-agent children run in their own Pi processes under their own supervisor
+     * (`subagents.ts`), they have their own stop and their own lifecycle, and a queue entry keyed by one
+     * would be claimed and delivered by the wrong owner.
+     */
+    conversationId: string;
+    content: string;
+    state: "queued" | "sending";
+    createdAt: string;
+    images?: MessageImage[];
+};
+/**
+ * What Pi reports about ITS OWN queue, forwarded to the browser as it arrives.
+ *
+ * `steering` and `followUp` are Pi's in-memory arrays as of this event (`agent-session.ts:204-208`).
+ * They are NOT the queue the user sees: the authoritative list is `AppState.queuedMessages`, and this
+ * is Pi's own view of the at most one steer that is currently in flight inside the child process. It
+ * is forwarded because it is the only signal that proves a steer was really picked up, and because a
+ * `followUp` array that is ever non-empty means something outside this server sent a `follow_up` -
+ * worth being able to see rather than infer.
+ */
+export type PiQueueSnapshot = {
+    steering: string[];
+    followUp: string[];
+};
+/**
+ * The nine methods Pi's `RpcExtensionUIRequest` union defines (rpc-types.ts:252-287), split by whether
+ * Pi waits for a reply. `blocking` is the only field the transport needs in order to decide, and it
+ * is derived here rather than at each call site so the two halves can never drift apart.
+ */
+export declare const EXTENSION_UI_METHODS: readonly ["select", "confirm", "input", "editor", "notify", "setStatus", "setWidget", "setTitle", "set_editor_text"];
+export type ExtensionUiMethod = (typeof EXTENSION_UI_METHODS)[number];
+/** Pi registers exactly these four in `pendingExtensionRequests`; the other five are fire-and-forget. */
+export declare const BLOCKING_UI_METHODS: ReadonlySet<string>;
+export type ExtensionUiNotifyType = "info" | "warning" | "error";
+export type ExtensionUiPlacement = "aboveEditor" | "belowEditor";
+/** One normalized `extension_ui_request`. The method-specific fields are only present for methods that send them. */
+export type ExtensionUiRequest = {
+    requestId: string;
+    method: ExtensionUiMethod;
+    /** True when Pi is blocked until the host answers. False means "display it, never ask the user to reply". */
+    blocking: boolean;
+    /** Pi omits `title` on notify/setStatus/setWidget/set_editor_text, so this is "" for those. */
+    title: string;
+    options?: string[];
+    /** confirm body, and the notify body. */
+    message?: string;
+    placeholder?: string;
+    prefill?: string;
+    /** Pi's own deadline in ms. `editor` never has one, which is why an unanswered editor waits forever. */
+    timeoutMs?: number;
+    notifyType?: ExtensionUiNotifyType;
+    statusKey?: string;
+    statusText?: string;
+    widgetKey?: string;
+    widgetLines?: string[];
+    widgetPlacement?: ExtensionUiPlacement;
+    text?: string;
+};
+export type ExtensionUiCloseReason = "answered" | "cancelled" | "timeout" | "aborted" | "expired";
+/** The answer a human gave. `cancelled` is Pi's third response shape: no answer was collected. */
+export type ExtensionUiAnswer = {
+    value?: string;
+    confirmed?: boolean;
+    cancelled?: true;
+};
+export type ClientCommand = {
+    type: "workspace.create";
+    name: string;
+    path?: string;
+} | {
+    type: "workspace.rename";
+    workspaceId: string;
+    name: string;
+} | {
+    type: "workspace.delete";
+    workspaceId: string;
+}
+/**
+ * Replaces BOTH workspace defaults in one shot, because the settings dialog saves them together.
+ * `null` clears a default back to "Pi's own" - a default the user removed must not persist as a
+ * value, or a new conversation would keep inheriting a choice the dialog no longer shows.
+ */
+ | {
+    type: "workspace.settings";
+    workspaceId: string;
+    model: {
+        provider: string;
+        modelId: string;
+    } | null;
+    thinkingLevel: string | null;
+    agentId?: string | null;
+} | {
+    type: "conversation.create";
+    workspaceId: string;
+} | {
+    type: "conversation.select";
+    conversationId: string;
+} | {
+    type: "conversation.archive";
+    conversationId: string;
+} | {
+    type: "conversation.unarchive";
+    conversationId: string;
+} | {
+    type: "conversation.rename";
+    conversationId: string;
+    name: string;
+}
+/**
+ * FORKS A WHOLE SESSION: a second conversation that starts from this one's complete history, in Pi's own
+ * transcript as well as in `state.json`.
+ *
+ * WHOLE SESSION, NOT A MESSAGE. Pi's own `fork` takes an `entryId` and branches from one message
+ * (`rpc-types.ts:62-66`, `agent-session-runtime.ts:279-287`); this takes no message id because the thing
+ * being asked for is a copy of the conversation as it stands, to be taken in another direction.
+ *
+ * WHY PI'S OWN `fork` IS NOT USED, which is the whole reason this command exists rather than a passthrough.
+ * Three separate reasons, and the first is not negotiable:
+ *
+ * 1. It TEARS THE RUNTIME DOWN AND SWITCHES TO THE NEW SESSION (`agent-session-runtime.ts:299-307`:
+ *    `teardownCurrent("fork", ...)` then `apply(createRuntime(...))`). Super Pi's "runtime" is one short-lived
+ *    Pi per turn (`runtime.ts:840` spawns, `:429-435` kills), so there is no runtime to hand across; there is
+ *    only a turn. Anything reached for here would have to be undone immediately.
+ * 2. It requires a long-lived child to fork FROM, which Super Pi deliberately does not have. Every piece of
+ *    Super Pi's session state is a durable file, and the process that used it is gone by the next turn.
+ * 3. Even given a live child, its result is only reachable through that child's runtime - the new session's
+ *    file is a side effect of the swap, not something a caller receives. Super Pi needs the file written
+ *    BEFORE the conversation exists, and needs to be told if it failed.
+ *
+ * So the fork is performed the same way a revert is: by asking Pi which file it uses for this id
+ * (`get_state.sessionFile`), checking that file belongs to the conversation being forked, and then writing a
+ * second file. See `runtime.ts` `fork()`.
+ */
+ | {
+    type: "conversation.fork";
+    conversationId: string;
+}
+/** Chooses the model for a conversation. Both fields are required because Pi's set_model needs both. */
+ | {
+    type: "conversation.model";
+    conversationId: string;
+    provider: string;
+    modelId: string;
+} | {
+    type: "conversation.thinking";
+    conversationId: string;
+    level: string;
+}
+/**
+ * Applies an agent to a conversation. `agentId: null` clears it back to Pi's own defaults, the same
+ * "absence means no value" rule the model and thinking selections follow.
+ *
+ * An agent that specifies a model or a thinking level does NOT set them here - it cannot, without
+ * knowing what the user has already chosen. It resolves them in the handler, where a user override
+ * that already exists is left alone, which is what makes the user's pick win over the agent's.
+ */
+ | {
+    type: "conversation.agent";
+    conversationId: string;
+    agentId: string | null;
+}
+/** Asks for the model/thinking catalog. Answered by `model.catalog`, never by an `error`. */
+ | {
+    type: "catalog.fetch";
+}
+/** Asks for the agent catalog read from disk. Answered by `agent.catalog`. */
+ | {
+    type: "agent.catalog.fetch";
+}
+/**
+ * Sends a message to a conversation, and THAT IS ALL IT CLAIMS.
+ *
+ * Whether the message starts a turn or joins the waiting queue is the SERVER's decision, made from
+ * the run guard in `index.ts`: a conversation with a turn in flight gets the message queued, an idle
+ * one gets a turn. The browser never picks, which is what makes the guard un-bypassable - the old
+ * arrangement had the browser decide by disabling itself, and a second WebSocket client (or a stale
+ * tab) walked straight past it into two Pi processes writing one session.
+ */
+ | {
+    type: "message.send";
+    conversationId: string;
+    content: string;
+    images?: MessageImage[];
+}
+/**
+ * Revert the conversation to the state right AFTER one message: every message after it is removed from
+ * BOTH histories, and no code file is touched.
+ *
+ * `messageId` names the message that SURVIVES. That is the same boundary OpenCode's revert draws
+ * (`DELETE FROM session_message WHERE seq > boundary.seq`, `packages/core/src/session/projector.ts:427-432`)
+ * and it is why this command takes no "how many messages" and no session id: the boundary is a thing the
+ * user can see and point at, and everything after it goes.
+ *
+ * No new conversation is created, ever. That is the user's hard requirement, and the reason it is worth
+ * stating here rather than only in the handler: Pi's own `fork()` cannot honour it (`fork()` always
+ * tears the runtime down and opens a new session file, `agent-session-runtime.ts:299-307`), so any
+ * implementation that reached for fork would break the promise without any type complaining.
+ */
+ | {
+    type: "message.revert";
+    conversationId: string;
+    messageId: string;
+}
+/**
+ * Drops ONE queued message, by Super Pi's id.
+ *
+ * Addressed by `queueId` rather than by text or by index for the reason `QueuedMessage.id` exists at
+ * all: two queued messages can be the same string, and a cancel that matched on text would drop
+ * whichever one sorted first. Refused for an entry already in `sending` - Pi holds that text now and
+ * cannot be told to forget one item - and an unknown or already-removed id is a no-op rather than an
+ * error, exactly as `subagent.stop` treats a run that has already settled.
+ */
+ | {
+    type: "message.cancel";
+    conversationId: string;
+    queueId: string;
+}
+/**
+ * Promotes one queued message to a `steer`: Pi takes it at the next turn boundary instead of waiting
+ * for the whole task to finish.
+ *
+ * The timing is Pi's and cannot be finer: `agent-loop.ts:295` polls steering after `turn_end`, which
+ * is after the WHOLE tool-call batch of one assistant message has finished (`agent-loop.ts:270`). So
+ * this means "after the tools currently running finish", and during a long single tool call there is
+ * nothing to interrupt - Pi offers no preemption. The UI says so in words rather than implying
+ * instant delivery.
+ */
+ | {
+    type: "message.steer";
+    conversationId: string;
+    queueId: string;
+} | {
+    type: "run.stop";
+    conversationId: string;
+}
+/**
+ * A HUMAN dispatches a sub-agent, with no model in the loop (design doc §3, entry 1).
+ *
+ * The three fields are the whole contract and none of them is optional: `conversationId` decides
+ * whose workspace the child runs in and whose transcript its card appears under, `agentId` must
+ * name a `mode: subagent` definition (the handler resolves it that way, so a primary agent is
+ * refused rather than quietly run as one), and `task` is what the child is asked to do. `task` has
+ * no maximum here because the cap in design §6 applies to what a MODEL is handed back, not to what
+ * a human may type; `SubagentSupervisor.run` refuses an empty one.
+ */
+ | {
+    type: "subagent.run";
+    conversationId: string;
+    agentId: string;
+    task: string;
+}
+/**
+ * Stops ONE sub-agent run, by id rather than by conversation.
+ *
+ * Id-keyed because a conversation may have several runs in flight at once and "stop" that kills
+ * every child of a conversation is a different, larger claim than the button on one card makes. A
+ * run id that is unknown, or already settled, is a no-op rather than an error: the card that sent
+ * this has usually just been told the run ended, and a stop that arrives late must not look like
+ * a failure.
+ */
+ | {
+    type: "subagent.stop";
+    runId: string;
+}
+/** Asks for the `mode: subagent` half of the agent directory. Answered by `subagent.catalog`. */
+ | {
+    type: "subagent.catalog.fetch";
+} | ({
+    type: "extension.ui.answer";
+    conversationId: string;
+    requestId: string;
+} & ExtensionUiAnswer);
+export type ServerEvent = {
+    type: "state";
+    state: AppState;
+} | {
+    type: "message.delta";
+    conversationId: string;
+    messageId: string;
+    delta: string;
+}
+/**
+ * THE ANSWER TO `conversation.fork`, as ONE event with an `ok` discriminant rather than two events or a
+ * bare `error`.
+ *
+ * WHY THIS EXISTS RATHER THAN REUSING `error`. The generic `error` event carries a message and nothing
+ * else, and the client's handler turns one into a banner over the whole pane. A fork that failed is a
+ * fact about ONE row of the sidebar, and the reader needs to know WHICH row: 「分叉失败：…」 with no
+ * conversation named leaves the user looking at a button that did nothing, which is the exact failure
+ * the requirement names. Two consequences, both load-bearing:
+ *
+ * - `conversationId` is on BOTH arms, so the browser can clear that row's pending state and re-enable
+ *   exactly the button that was pressed. Nothing else in the protocol can be correlated to the press.
+ * - The failure arm is a SENTENCE (`message`), produced by the same code that produced the refusal, so
+ *   the reason the server refused is the reason shown. A boolean would be a dead click.
+ *
+ * It is ALSO why the handler catches instead of letting a fork throw: a thrown command becomes a
+ * broadcast `error` to every connected browser, which would blame an unrelated pane in another tab.
+ *
+ * The success arm reports `messagesCopied` because "the fork happened" and "the fork happened completely"
+ * are different claims, and a whole-session fork of a conversation whose Pi transcript could not be
+ * located is a copy of the visible half only.
+ */
+ | ({
+    type: "conversation.fork.result";
+    conversationId: string;
+} & ({
+    ok: true;
+    forkedId: string;
+    title: string;
+    messagesCopied: number;
+    piSessionFile?: string;
+} | {
+    ok: false;
+    message: string;
+}))
+/**
+ * Every tool call made while filling one message, as a whole SNAPSHOT.
+ *
+ * A snapshot for the same reason `subagent.event` is one and `message.delta` is a delta: `state` carries
+ * the same array, so a reload or a reconnect rebuilds every block from the file, and a browser that missed
+ * an event must not be left holding a half-built row. The difference from `message.delta` is that this one
+ * CANNOT be a delta - the fields change on a row rather than append to a string, and "apply this patch"
+ * is an instruction the client has to be trusted to apply correctly.
+ *
+ * Sent on `tool_execution_start` and again on `tool_execution_end`, so a block appears the moment a call
+ * begins rather than when the whole turn ends. That is what makes a long tool call visible while it is
+ * running - and a call that starts and never ends leaves a row with no `status`, which is exactly how a
+ * block says "still in flight" instead of claiming an outcome nobody reported.
+ */
+ | {
+    type: "message.tools";
+    conversationId: string;
+    messageId: string;
+    toolCalls: ToolCallBlock[];
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "extension.ui";
+    conversationId: string;
+    request: ExtensionUiRequest;
+} | {
+    type: "extension.ui.closed";
+    conversationId: string;
+    requestId: string;
+    reason: ExtensionUiCloseReason;
+} | {
+    type: "model.catalog";
+    catalog: ModelCatalog;
+} | {
+    type: "agent.catalog";
+    catalog: AgentCatalog;
+}
+/**
+ * The `mode: subagent` half of the same directory, as its OWN event rather than an extra key on
+ * `agent.catalog`.
+ *
+ * Split because the two rosters are kept apart everywhere else - `readAgents` filters by mode, the
+ * primary picker never sees a sub-agent and vice versa - and folding them into one payload would
+ * hand the browser a list it must then filter correctly, which is precisely the invariant that has
+ * to hold. Two catalogs, each already filtered at the source, cannot leak across.
+ */
+ | {
+    type: "subagent.catalog";
+    catalog: AgentCatalog;
+}
+/**
+ * The current SNAPSHOT of one sub-agent run, sent on every text delta rather than once at the end.
+ *
+ * A snapshot rather than a delta for the same reason `state` is one: a card that assembles itself
+ * from a missed event is a card that can be wrong, and this event has to survive a reconnect race and
+ * an out-of-order drop. The price is that each one serializes the run so far, which is exactly why
+ * `SubagentRun` holds the last assistant message and not the transcript.
+ */
+ | {
+    type: "subagent.event";
+    run: SubagentRun;
+}
+/**
+ * Pi's own queue snapshot, forwarded the moment `queue_update` arrives on the child's stdout.
+ *
+ * A new event rather than another key on `state` because it is a different thing with a different
+ * lifetime: `state` carries the durable waiting list, this carries what the live child process is
+ * holding right now and changes many times within a single turn. Keeping them apart is also what stops
+ * the two from being confused for one source of truth - the browser renders the dock from `state` and
+ * only annotates it with this.
+ */
+ | ({
+    type: "pi.queue";
+    conversationId: string;
+} & PiQueueSnapshot);