@evandu/super-pi 0.0.0-stage → 0.1.0

package/dist/server/server-context.d.ts

@@ -0,0 +1,46 @@
+import type { Store } from "./store.js";
+import type { AgentRuntime } from "./runtime.js";
+import type { SubagentRunRecorder } from "./subagent-runs.js";
+import type { ServerEvent } from "./types.js";
+import type { WorkspaceService } from "./application/workspace-service.js";
+import type { ConversationService } from "./application/conversation-service.js";
+import type { RunService } from "./application/run-service.js";
+import type { ExtensionUiService } from "./application/extension-ui-service.js";
+import type { CatalogService } from "./application/catalog-service.js";
+/**
+ * Common filesystem paths used across the server.
+ */
+export interface ServerPaths {
+    dataDir: string;
+    rootDir: string;
+    agentsDir: string;
+    agentPromptDir?: string;
+    uploadsDir: string;
+    clientDir: string;
+}
+/**
+ * EventBroadcaster abstracts the WebSocket transport's broadcast mechanism
+ * so application services do not directly couple to WebSocket connections.
+ */
+export interface EventBroadcaster {
+    /** Broadcast a server event to all connected clients. */
+    broadcast(event: ServerEvent): void;
+    /** Broadcast the current state snapshot to all connected clients. */
+    broadcastState(): void;
+}
+/**
+ * Central server context containing infrastructure dependencies and application services.
+ */
+export interface ServerContext {
+    paths: ServerPaths;
+    store: Store;
+    runtime: AgentRuntime;
+    subagents: SubagentRunRecorder;
+    broadcaster: EventBroadcaster;
+    accessToken?: string;
+    workspaceService: WorkspaceService;
+    conversationService: ConversationService;
+    runService: RunService;
+    extensionUiService: ExtensionUiService;
+    catalogService: CatalogService;
+}

package/dist/server/server-context.js

@@ -0,0 +1 @@
+export {};

package/dist/server/store.d.ts

@@ -0,0 +1,424 @@
+import type { AppState, Conversation, Message, MessageImage, ModelSelection, QueuedMessage, SubagentRun, SubagentRunUpdate, TodoItem, ToolCallBlock, Workspace } from "./types.js";
+/** Mints the id a forked conversation will have, BEFORE its Pi transcript exists.
+ *
+ *  Exported because the ordering demands it and no other arrangement provides it. Pi's copied file's header
+ *  `id` has to BE the new conversation's id (it is what `findLocalSessionByExactId` matches), so the id has
+ *  to be decided before the file is written; and the conversation must not exist until the file is safely on
+ *  disk, or a failed write would leave a conversation whose model context is silently empty. The runtime is
+ *  therefore handed the id and the store is handed the same one back. See `ForkRequest.forkedConversationId`. */
+export declare function newConversationId(): string;
+/**
+ * How many SETTLED sub-agent runs `state.json` keeps, so the file cannot grow without bound.
+ *
+ * WHY A BOUND IS NEEDED AT ALL. `beginSubagentRun` unshifts and nothing ever removes a run, so a long
+ * session that dispatches sub-agents - which is exactly what this feature encourages - would otherwise
+ * accumulate records forever. The file is not a log on disk that costs nothing to grow: it is rewritten
+ * in full on EVERY text delta of EVERY running child (see `SubagentRunRecorder.publish`), cloned into
+ * the browser on every `state` broadcast, and read at startup. A run record is bounded but not small -
+ * `output` is the last assistant message, up to the 50 KB cap of §6, plus the task text and one label
+ * per tool call - so an unbounded array makes every one of those operations slower for everybody.
+ *
+ * WHY 100. It has to be big enough that a person can scroll back through a working day without a card
+ * going missing, and small enough that the worst case stays in the range a JSON file and a browser
+ * snapshot handle comfortably. At 100 settled runs, and a deliberately pessimistic 50 KB per output,
+ * the array is ~5 MB; at 1000 it would be ~50 MB, which is enough to be felt as the app hanging on
+ * every broadcast. 100 is roughly a day's worth of sub-agent work for a person using this as a tool
+ * rather than as a load generator, and a run older than that is still recoverable in full through Pi -
+ * the record carries `sessionId`, and `switch_session` or `export_html` reads the real transcript. So
+ * what the bound costs is a scrollback affordance, not history.
+ *
+ * Exported so a test can assert the bound against the same number the store uses rather than
+ * re-deriving it.
+ */
+export declare const SUBAGENT_RUN_RETENTION = 100;
+/**
+ * Everything a revert decided, before anything is changed.
+ *
+ * TWO CALLERS NEED IT, and they must agree exactly: the server has to know which sub-agent children to
+ * STOP before it cuts the history out from under them, and the store has to know which records to delete
+ * afterwards. Two independently written answers to "what does this revert remove" would eventually
+ * disagree, and the shape of that disagreement is the worst one available - a stopped child whose record
+ * survives, or a deleted record for a child that is still running and still streaming into a store it is
+ * no longer in. So both read this one function, which touches nothing.
+ */
+export type RevertPlan = {
+    /** Index of the message that SURVIVES. Everything from `boundaryIndex + 1` is removed. */
+    boundaryIndex: number;
+    /** Pi's entry id of the surviving message - the line Pi's file is cut at. */
+    boundaryEntryId: string;
+    /** The messages that go away, oldest first. */
+    removedMessageIds: string[];
+    /**
+     * Sub-agent runs dispatched by a turn that is being removed, so their records point at a transcript
+     * that no longer exists (research §5 pitfall 7). Runs from surviving turns are deliberately NOT here:
+     * `trimSubagentRuns` refuses to drop a live conversation's settled runs (`store.ts:183-195`), so a
+     * revert has to drop these explicitly or they become permanent orphans.
+     */
+    doomedRunIds: string[];
+};
+export declare class Store {
+    private readonly filePath;
+    private state;
+    private constructor();
+    static open(filePath: string): Promise<Store>;
+    snapshot(): AppState;
+    createWorkspace(name: string, path?: string): Promise<Workspace>;
+    renameWorkspace(workspaceId: string, name: string): Promise<Workspace>;
+    /**
+     * Replaces the workspace's two defaults. `undefined` DELETES the key rather than storing Pi's
+     * default as this app's state - the same convention as setConversationThinking, and for the same
+     * reason: "follow Pi" must be the absence of a value, not a frozen copy of whatever Pi's default
+     * happened to be when the dialog was saved. Only conversations created AFTER this call ever see
+     * the new values; existing ones are not migrated, by design.
+     */
+    /**
+     * Replaces the workspace's defaults. `model`/`thinkingLevel` are ALWAYS sent whole (null clears one of
+     * them); `agentId` is tri-state, which is why it is not part of that pair: a string sets it, `null`
+     * clears it, and `undefined` leaves it alone. Bundling a tri-state field into an "absent means delete"
+     * pair would make any caller that only wanted to change the model silently drop the default agent.
+     *
+     * ONE persist for all three, deliberately. Two writes would publish an intermediate state - the pair
+     * saved but not the agent - and the window between them is observable: a client that reopens the
+     * settings dialog after seeing the first write on disk would mount from a broadcast that has not been
+     * sent yet, and its draft would then be frozen at the stale value. One write, one broadcast, no window.
+     */
+    setWorkspaceDefaults(workspaceId: string, defaults: {
+        model?: ModelSelection;
+        thinkingLevel?: string;
+        agentId?: string | null;
+    }): Promise<Workspace>;
+    deleteWorkspace(workspaceId: string): Promise<string[]>;
+    createConversation(workspaceId: string): Promise<Conversation>;
+    /**
+     * Copies a conversation into a NEW one, under an id the caller has already minted.
+     *
+     * THE ID IS A PARAMETER, and that is the whole reason this method does not simply mint one: the caller had
+     * to write Pi's copied transcript under that id first (see `ForkRequest.forkedConversationId`), so by the
+     * time this runs the id is already the one on disk. Minting here as well would produce a conversation whose
+     * Pi file belongs to a different, nonexistent conversation - the exact "Pi opens an empty session and the
+     * history has vanished with no error anywhere" failure probe B was about.
+     *
+     * WHAT IS COPIED, FIELD BY FIELD AND NEVER BY A SPREAD, for the same reason `createConversation` writes out
+     * three fields individually: the type declares exactly these, so a spread would quietly start persisting
+     * whatever the next person adds to `Conversation`. The workspace, the model, the thinking level and the
+     * agent are all copied, because a fork that came back on a different model or with no role would not be
+     * the conversation the user forked.
+     *
+     * `title` is copied VERBATIM, unchanged. Not a reason, not a suffix: the fork IS this conversation, and
+     * inventing a name is a product decision the request did not delegate. Renaming it is one click and always
+     * available, which is better than a label nobody chose.
+     *
+     * MESSAGES ARE COPIED WITH FRESH `id`s AND THE ORIGINAL `piEntryId`s. Both halves matter:
+     *
+     * - Fresh ids, because `Message.id` is this store's own handle (`beginAssistantMessage`,
+     *   `appendToolCall` and `appendAssistantDelta` all find a message by it) and a forked conversation that
+     *   answered to its source's ids would be one object wearing two names. Fork the same conversation twice
+     *   and the two copies are distinct records.
+     * - The ORIGINAL `piEntryId`, because that is the whole reason the fork is a fork. Pi's copied file is
+     *   byte-identical apart from two header fields (see `forkSessionFile`), so the source's entry ids are
+     *   present and valid in the fork - and a copied message keeps the ability to be a REVERT boundary in the
+     *   conversation it was copied into. Dropping the ids would produce a fork whose history cannot be
+     *   reverted at all, which is a silent loss of a feature rather than an honest absence.
+     *
+     * `status` is `"idle"` unconditionally, even when the source is running, because the caller refuses a
+     * running source outright (`runtime.fork`) and a conversation that has never run a turn must not be born
+     * claiming to be in one. `error` is NOT copied: it describes a run, and this conversation has had none.
+     *
+     * NOT COPIED, and both omissions are deliberate and both are the same judgement - they belong to a RUN,
+     * and no run was copied: `subagentRuns` are filtered by `conversationId`, so a run dispatched by the source
+     * stays with the source; a run dispatched by the FORK will be filed under the fork's own id and work as
+     * usual. `queuedMessages` likewise, for the same reason (research pitfall 7): a message waiting for a turn
+     * that was never copied must not be re-sent into a different conversation.
+     *
+     * POSITION IS NOT CHOSEN HERE. `unshift` plus the client rendering the sidebar by `updatedAt`
+     * (`byRecency`) puts a fork at the TOP of its workspace group, because `updatedAt` is now - which is the
+     * same position a newly created conversation takes, and the same reason.
+     */
+    forkConversation(sourceConversationId: string, forkedConversationId: string): Promise<Conversation>;
+    /**
+     * Archive is a marker, not a move: the conversation keeps its id, workspace, messages and position.
+     * `updatedAt` is deliberately NOT touched, because it drives the sidebar's live timestamp and recency -
+     * bumping it would teleport the row to the top of the list the instant it was archived.
+     *
+     * A running conversation is rejected rather than archived. An archived conversation cannot be opened,
+     * so allowing one would leave a run streaming into a pane the user can no longer reach, along with any
+     * Extension UI question it is blocked on. Refusing keeps the rule honest and leaves stop-then-archive
+     * to the user, which is a visible choice instead of a silent one.
+     */
+    archiveConversation(conversationId: string): Promise<void>;
+    /** Restoring deletes the key rather than setting it to null, so a fully restored conversation serializes
+     *  byte-identically to one that was never archived. `delete` is legal here because the field is optional. */
+    unarchiveConversation(conversationId: string): Promise<void>;
+    /**
+     * Rename edits the title and NOTHING else. In particular `updatedAt` is deliberately not touched,
+     * for exactly the reason archive is: `updatedAt` is the sidebar's recency key, so bumping it would
+     * teleport the row to the top of the live list because someone retitled it. Renaming is not activity.
+     *
+     * There is no uniqueness check, and there is no status check on purpose. `createWorkspace` does not
+     * reject a duplicate name either, so rejecting one here would make the two paths disagree about the
+     * same question; two rows reading "notes" is a cosmetic problem the user can see and fix. And a
+     * RUNNING conversation stays renameable: the title is display-only, the run is unaffected, and
+     * refusing would mean a conversation could be permanently un-renameable while the agent works.
+     *
+     * Archived conversations are renameable too - archiving folds a row away, it does not delete it, and
+     * the Archived group renders the same name.
+     */
+    renameConversation(conversationId: string, name: string): Promise<Conversation>;
+    addUserMessage(conversationId: string, content: string, images?: MessageImage[]): Promise<Message>;
+    /**
+     * Records the model a conversation runs on. `updatedAt` is deliberately NOT touched, for the same
+     * reason rename does not touch it: it is the sidebar's recency key, and switching model is not
+     * activity in the conversation. No status check either - changing the model of a RUNNING
+     * conversation is allowed, because the selection is read at the START of the next turn, so the
+     * turn in flight is unaffected and refusing would strand a conversation on a model the user can
+     * no longer change until it settles.
+     */
+    setConversationModel(conversationId: string, model: ModelSelection): Promise<Conversation>;
+    /** Restoring Pi's own default deletes the key rather than storing Pi's default as this app's state. */
+    setConversationThinking(conversationId: string, level: string | undefined): Promise<Conversation>;
+    /**
+     * Records the agent a conversation runs as. Same three rules as `setConversationModel`: `undefined`
+     * DELETES the key rather than freezing "no agent" as a value, `updatedAt` is untouched because
+     * changing role is not activity in the conversation, and no status check - the agent is read at the
+     * START of the next turn, so the turn in flight is unaffected.
+     */
+    setConversationAgent(conversationId: string, agentId: string | undefined): Promise<Conversation>;
+    beginAssistantMessage(conversationId: string): Promise<Message>;
+    appendAssistantDelta(conversationId: string, messageId: string, delta: string): Promise<void>;
+    /**
+     * Appends one tool call to the message it belongs to, and returns the message's whole `toolCalls`
+     * array so the caller can broadcast it as one snapshot.
+     *
+     * WHY AN APPEND AND NOT AN UPDATE, and why the returned array is the whole truth. A turn's calls arrive
+     * one at a time and each one REWRITES a field on a row it has already broadcast - `status` and
+     * `durationMs` land on `tool_execution_end`, minutes or seconds after the row was published by
+     * `tool_execution_start`. So the only thing that can be cheap and correct is: the store owns the array,
+     * the caller sends the array. Handing back the array rather than the one row is what stops the two from
+     * drifting - the caller has nothing to merge, so there is no merge to get wrong, and the event it sends
+     * is the same shape `state` carries on the next broadcast.
+     *
+     * PERSISTED ON EVERY CALL, for the same reason `appendAssistantDelta` is: a block that was on screen
+     * when the browser reloaded has to come back, and a reload that showed a `read` but not the `bash` that
+     * followed it would be worse than showing neither.
+     *
+     * `toolCalls` is CREATED LAZILY, so a message whose turn used no tools stores no empty array - which is
+     * what makes a `state.json` written before call blocks existed read as "this turn used no tools"
+     * instead of as a field it does not understand.
+     */
+    appendToolCall(conversationId: string, messageId: string, call: ToolCallBlock): Promise<ToolCallBlock[]>;
+    /**
+     * Fills in the outcome of the call at `index`, or returns the array UNCHANGED when there is no such
+     * index.
+     *
+     * ADDRESSED BY POSITION rather than by Pi's `toolCallId`, and that is the whole reason the caller has
+     * to hold a map. `toolCallId` is an identity only Pi can resolve - it is never persisted on
+     * `ToolCallBlock` - so the caller resolves each end back to the row it started, which is exactly what
+     * `SubagentRunRecorder` does for a card.
+     *
+     * A MISMATCH IS NOT AN ERROR. `tool_execution_end` with no matching start, or one that arrives after the
+     * turn ended, must not fail the turn: the alternative is a store method that throws inside a drain loop,
+     * and the reader would lose the whole turn's transcript over one unresolvable id. Returning the array
+     * unchanged keeps the caller broadcasting what it actually knows.
+     *
+     * Only `status` and `durationMs` are written, and only when they are present on the incoming block - a
+     * second end for a row that already has an outcome must not erase it with an absent field.
+     */
+    settleToolCall(conversationId: string, messageId: string, index: number, outcome: {
+        status?: "ok" | "error";
+        durationMs?: number;
+    }): Promise<ToolCallBlock[]>;
+    setStatus(conversationId: string, status: Conversation["status"]): Promise<void>;
+    /** The plan a revert would carry out, without carrying it out. The server reads this to stop children first. */
+    planRevert(conversationId: string, messageId: string): RevertPlan;
+    /**
+     * Records which Pi entry a message became, as reported by Pi while it was still running.
+     *
+     * Only ever set, never cleared: a message that already has an id keeps the one Pi gave it for that
+     * turn, and a second report for the same message is ignored rather than allowed to move the boundary -
+     * a boundary that moved under a user who is looking at it is exactly the silent data loss revert must not
+     * be able to cause. An unknown message id is refused for the same reason `appendAssistantDelta` refuses
+     * one: it means the caller and the store disagree about the conversation, and guessing is worse.
+     */
+    setMessagePiEntryId(conversationId: string, messageId: string, piEntryId: string): Promise<void>;
+    /**
+     * Reverts the conversation to the state right after `messageId`, in `state.json` only.
+     *
+     * SCOPE, DELIBERATELY NARROW: this touches `messages` and `subagentRuns` and nothing else. It does not
+     * touch the workspace (that is not this process's to touch), it does not create or modify a conversation
+     * (the user's hard requirement: still the same session, same id, same row in the sidebar), and it does
+     * not record a "revert happened" marker - there is no undo to restore one for.
+     *
+     * NOT `updatedAt`. For the same reason rename and archive leave it alone: it is the sidebar's recency key,
+     * so bumping it would teleport the conversation to the top of the list as a side effect of editing its
+     * history. What a person did to a transcript is not activity IN the conversation, and the timestamps of
+     * the surviving messages are untouched, so the pane's own ordering does not move either.
+     *
+     * `planRevert` has already run by the time this is called (the server reads it to stop children), so the
+     * plan is recomputed here rather than passed in - two callers cannot disagree about what a message id
+     * means, and the recomputation is a pure scan of a small array.
+     */
+    revertMessages(conversationId: string, messageId: string): Promise<RevertPlan>;
+    private requireConversation;
+    /**
+     * This conversation's waiting list, oldest first.
+     *
+     * Cloned like every other value this store hands out, because the caller broadcasts it straight to
+     * browsers and the array is mutated in place by the very next enqueue.
+     */
+    listQueuedMessages(conversationId: string): QueuedMessage[];
+    /**
+     * Adds one message to the waiting list and returns it.
+     *
+     * The id is minted here and is the entry's identity for its whole life. Pi matches its own queue by
+     * message TEXT (`agent-session.ts:1123`), so two identical messages are one entry to Pi and two here;
+     * `cancel` and `steer` name the id, which is the only reason "cancel the second of two identical
+     * messages" is expressible at all. `crypto.randomUUID`, like every other id in this store.
+     */
+    enqueueMessage(conversationId: string, content: string, images?: MessageImage[]): Promise<QueuedMessage>;
+    /**
+     * Removes one waiting message. Returns it, or `undefined` when it is already gone.
+     *
+     * "Already gone" is a no-op rather than an error, and the reason is the same as `SubagentRun.stop`:
+     * the click that sent this was almost always triggered by a dock row the browser has not been told
+     * about yet, so an id that has already been delivered or cancelled is the ordinary case and must not
+     * surface as a failure.
+     *
+     * A `sending` entry REFUSES, because the text is already in a live Pi child's stdin and Pi has no way
+     * to forget one item (its only queue command is `clear_queue`, which clears every one of them,
+     * including follow-ups that have nothing to do with this click). Removing it from this list would not
+     * stop Pi from delivering it - it would make the model act on a message the user believed they had
+     * withdrawn.
+     */
+    cancelQueuedMessage(conversationId: string, queueId: string): Promise<QueuedMessage | undefined>;
+    /**
+     * Claims one waiting message for delivery to the live Pi process: `queued` becomes `sending`, and the
+     * entry STAYS in the list until Pi reports it delivered.
+     *
+     * The read and the write are adjacent statements with no `await` between them, which is what makes
+     * the claim atomic here. This store has no mutex, and it does not need one: JavaScript runs this
+     * synchronous run-to-completion, so a second caller arriving in the same tick observes the write above
+     * and cannot claim the same entry. Anything that needed to await between reading and writing would
+     * need real serialization instead.
+     *
+     * Throws for an unknown id and for one that is already `sending`, because both mean the caller is
+     * acting on a state the store has already moved past - and the second one means a second steer of the
+     * same message would put the text into Pi twice.
+     */
+    claimQueuedMessage(conversationId: string, queueId: string): Promise<QueuedMessage>;
+    /**
+     * Puts a `sending` entry back into the queue.
+     *
+     * The one legal use, and it is narrow on purpose: this is called ONLY when we can prove the message
+     * never reached a model - the turn ended while Pi still held it, or the write to Pi's stdin failed
+     * before it left. Pi drains steering before its loop can end and reports the removal before the
+     * delivered message, so a message still `sending` when the child is gone provably was not delivered,
+     * and returning it is a fact rather than a guess. It is deliberately NOT used for "Pi has not answered
+     * yet" (see `steer` in `index.ts`), where the outcome is genuinely unknown and the honest state is
+     * still `sending`.
+     */
+    releaseQueuedMessage(queueId: string): Promise<void>;
+    /**
+     * Removes the OLDEST `count` messages this conversation has in `sending`, and returns them.
+     *
+     * Driven by a COUNT rather than by matching text, and that is the whole point. Pi's `queue_update`
+     * reports only the strings it still holds, and Pi itself identifies which of its entries a delivered
+     * message came from with `indexOf` on that text - so with two identical steered messages, "which one
+     * was delivered" is exactly the question Pi cannot answer. It does not need to be answered: Pi's
+     * steering queue is FIFO and Super Pi only ever steers from the front of this list, so a drop in
+     * `steering.length` from N to N-k means Super Pi's oldest k `sending` entries were delivered, in
+     * order, whatever their text was.
+     */
+    dropSendingMessages(conversationId: string, count: number): Promise<QueuedMessage[]>;
+    /**
+     * Takes the oldest still-`queued` message of this conversation OUT of the list and returns it, for the
+     * next turn to send as its prompt.
+     *
+     * Removing it here, rather than marking it and removing it after the turn, is what bounds the loop:
+     * every pass through the follow-up loop strictly shrinks the list, so the loop cannot run forever
+     * even if a turn succeeds without consuming anything. And removing it BEFORE the spawn is what makes a
+     * crash honest - a server that dies mid-turn has already taken the message out of the file, and
+     * `open` does not put it back, because it may well have been delivered.
+     */
+    takeNextQueuedMessage(conversationId: string): Promise<QueuedMessage | undefined>;
+    /**
+     * Returns every `sending` message of this conversation to the queue, for the end of a turn.
+     *
+     * See `releaseQueuedMessage` for why this is a fact and not a guess, and `reconcileQueuedMessages` for
+     * why the same treatment is right after a crash. Called both when a turn ends and when the user stops
+     * it: in the stop case the child is killed mid-turn and a steer it was still holding was never
+     * delivered either, so putting it back is what lets the user decide what to do with it instead of
+     * silently dropping a message they typed.
+     */
+    releaseSendingMessages(conversationId: string): Promise<void>;
+    /**
+     * Records a sub-agent run as `running`, BEFORE the child is spawned.
+     *
+     * The ordering is the whole point of this method existing separately from the spawn. A record created
+     * after the child starts cannot survive the child failing to start, and one created only at the end
+     * leaves nothing behind when the SERVER dies - which is the orphan startup reconciliation exists to
+     * clean up. Writing the claim first is what makes that orphan possible, and therefore recoverable.
+     *
+     * `unshift`, like `createConversation`: the newest run is the one a reader is looking for.
+     *
+     * Trimmed HERE rather than at read time, because the array in memory and the file on disk have to
+     * be the same thing - a store that kept evicted rows until the next unrelated write would put them
+     * back on disk, and one that trimmed on read would show a browser a roster the file still holds.
+     */
+    beginSubagentRun(run: SubagentRun): Promise<SubagentRun>;
+    setBackgroundTask(summary: AppState["backgroundTasks"][number]): Promise<void>;
+    removeBackgroundTask(id: string): Promise<void>;
+    /**
+     * Applies the fields a run's life can change, and nothing else.
+     *
+     * `Object.assign` is safe HERE in a way it is not in `setConversationModel`, and the difference is the
+     * patch's own type: `SubagentRunUpdate` is a named list of six already-narrowed fields, so there is no
+     * wider object for a spread to smuggle extra keys in from. `undefined` means "no such value" and is
+     * dropped by JSON.stringify, which is how `output`/`error`/`outputTruncated` come to be absent rather
+     * than stored as an empty or null one.
+     *
+     * PERSISTED ON EVERY CALL, exactly as `appendAssistantDelta` is: the record a reader sees in a
+     * `state` broadcast and the record on disk are then never different, and a run that is in flight is
+     * as durable as the conversation it belongs to.
+     */
+    setSubagentRun(runId: string, changes: SubagentRunUpdate): Promise<SubagentRun>;
+    /**
+     * Replaces the model's task list, and persists it.
+     *
+     * WHY IT IS A FILE AND NOT PI'S MEMORY, stated once here because it is the whole justification: Pi is
+     * killed unconditionally at the end of every turn (`runtime.ts`) and never writes a tool result it was
+     * given by an extension anywhere durable except the session JSONL, so a list held only in the child
+     * would be gone before a person could look at it - and the sidebar would empty itself at every turn
+     * boundary. The list is therefore part of `state.json` and rides the existing broadcast, which is also
+     * why the browser needs no channel of its own: it already repaints from `state` on every text delta.
+     *
+     * THE PARAMETER IS RE-NORMALIZED HERE, not trusted because the endpoint normalized it. Those are two
+     * different things: `/api/todos` validates a request that crossed a socket, and this validates a value
+     * handed to `setTodos` by any future caller inside this process. A method whose own contract is "call me
+     * with anything" is the only version of this that cannot be broken by the next call site.
+     *
+     * AN EMPTY LIST IS STORED AS ABSENCE, not as `[]`. `normalizeTodos` returns `[]` for a list the model
+     * emptied deliberately, and the two must not be distinguishable: the browser renders `todos: []` and
+     * `todos: undefined` as the same empty state on purpose, and persisting `[]` for a store that has never
+     * seen the tool would make a fresh install claim the model had considered a plan and found none. So the
+     * key is deleted, which also keeps `state.json` free of a field no build before this one wrote.
+     */
+    setTodos(raw: unknown): Promise<{
+        todos: TodoItem[];
+        dropped: number;
+    }>;
+    /**
+     * Writes the whole state atomically: a temp file, then a rename over the real one.
+     *
+     * SERIALIZED, because two conversations can genuinely run at once (see workspace-cwd.test.mjs), and
+     * this method was not safe for that: every write used the SAME `${filePath}.tmp`, so two overlapping
+     * persists raced and the loser's rename failed with ENOENT on a file the winner had already moved.
+     * A unique name per write would hide that ENOENT while leaving the real bug in place - whichever rename
+     * landed last would win, and a rename of an OLDER snapshot last would silently discard a newer one.
+     * Queueing keeps both properties: one writer at a time, and last write wins with the newest state.
+     *
+     * A rejected write must not poison the queue, or one failure would reject every later persist as well.
+     */
+    private persistQueue;
+    private persist;
+}
+export declare function defaultStorePath(dataDir: string): string;