@evandu/super-pi 0.1.94 → 0.1.95

package/dist/server/runtime.js

@@ -8,9 +8,16 @@ import { mkdir, stat } from "node:fs/promises";
 import { forkSessionFile, truncateSessionFile } from "./session-repository.js";
 export { forkSessionFile, truncateSessionFile } from "./session-repository.js";
 import { resolve, join } from "node:path";
-import { agentSpawnArgs, readAgents } from "./agents.js";
+import { agentSpawnArgs, readAgents, toolSelection, writeAgentPrompt } from "./agents.js";
 import { TASK_CAPABILITY_ENV, mintCapability, releaseCapability } from "./capability.js";
 import { resolvePiCommand, shellQuote } from "./pi-command.js";
+import { PiSessionPool, repositoryRootFrom } from "./pi-session-pool.js";
+import { describeDeliveredUserMessage, describePiQueue, handleSessionEvent, TurnQueue } from "./pi-session-events.js";
+// The queue/steer recognisers live in pi-session-events.ts, where the SESSION path's bridge can use
+// them; the one-shot drain loop below reads the same records through the same two functions, so both
+// paths recognise a delivery identically. Re-exported because they were part of this module's surface.
+export { describeDeliveredUserMessage, describePiQueue } from "./pi-session-events.js";
+import { createPiSession, piSdkAvailable, superPiExtensionPaths } from "./pi-session.js";
 import { TASK_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_EXEC_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, WORKFLOW_ENDPOINT_ENV, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, rosterPayload, } from "./task-tool.js";
 import { BLOCKING_UI_METHODS, EXTENSION_UI_METHODS, } from "./types.js";
 import { loadConversationImages } from "./upload.js";
@@ -43,54 +50,6 @@ export class WelcomeRuntime {
         return { source: "unavailable", models: [], levels: [], fetchedAt: new Date().toISOString(), error: "Welcome runtime has no Pi session to ask" };
     }
 }
-/**
- * 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.
- */
-/**
- * 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 function describePiQueue(record) {
-    if (record.type !== "queue_update")
-        return undefined;
-    return { steering: textList(record.steering) ?? [], followUp: textList(record.followUp) ?? [] };
-}
-/**
- * Reads the text of a steer Pi has just delivered, or undefined when this record is not one.
- *
- * A `message_start` carrying a `user` message is exactly that, and nothing else is: the prompt that
- * opened the turn is never re-announced this way, and `assistant` messages are not deliveries.
- *
- * Content is joined with a newline rather than taken from the first block, so a multi-block steer comes
- * back as the text the user actually wrote instead of its first paragraph. The text is a MATCHING HINT
- * only - Pi identifies its own queued entry by `indexOf` on this string (`agent-session.ts:1123`) and so
- * cannot tell two identical messages apart either, which is why the caller resolves a delivery by
- * position and not by comparing this.
- */
-export function describeDeliveredUserMessage(record) {
-    if (record.type !== "message_start")
-        return undefined;
-    const message = record.message;
-    if (!message || typeof message !== "object" || message.role !== "user")
-        return undefined;
-    const content = message.content;
-    if (!Array.isArray(content))
-        return undefined;
-    const parts = content
-        .map((block) => (block && typeof block === "object" && typeof block.text === "string" ? block.text : undefined))
-        .filter((part) => part !== undefined);
-    return parts.length ? parts.join("\n") : undefined;
-}
 const NOTIFY_TYPES = new Set(["info", "warning", "error"]);
 const PLACEMENTS = new Set(["aboveEditor", "belowEditor"]);
 const text = (value) => (typeof value === "string" ? value : undefined);
@@ -287,6 +246,43 @@ export class PiRpcRuntime {
     knowledge;
     setKnowledge(knowledge) { this.knowledge = knowledge; }
     runs = new Map();
+    /**
+     * THE LIVE SESSIONS, one per conversation, alive across turns.
+     *
+     * `runs` is the OLD registry - a child that exists only while a turn is running - and it still
+     * describes the one-shot paths (memory review, knowledge rerank, catalog probe), which keep their
+     * own throwaway children. The main conversation path does NOT use it: a conversation's session lives
+     * in the pool, and a turn is a run ON that session rather than a process OF its own.
+     */
+    sessionPool;
+    /**
+     * The turn currently running on each conversation's session.
+     *
+     * This is the piece the old design did not need, because a turn WAS a process and the process
+     * registry said everything. With a session that outlives its turns, the host has to know which turn
+     * is on the session RIGHT NOW - that is what an abort targets, and what a steer is delivered into.
+     */
+    activeTurns = new Map();
+    /**
+     * THE CURRENT TURN'S EXTENSION-UI HOST, per conversation.
+     *
+     * Pi's blocking UI questions (`select`/`confirm`/`input`/`editor`) are answered by a host, and the
+     * host is a per-TURN thing - `run-service` builds one per `answer()` call - while the UI context the
+     * session's extensions talk to is bound ONCE per session. This map is the bridge between the two
+     * lifetimes: a turn registers its host here for exactly its own duration, and the session's bound
+     * context reads through it at call time. A question asked while no turn is registered gets the honest
+     * answer - `cancelled` - never a default, which is the same rule the RPC path's no-host branch follows.
+     */
+    sessionHosts = new Map();
+    /** The sessions whose extension runner already has the UI bridge bound. */
+    uiBoundSessions = new WeakSet();
+    /**
+     * The session-file path last reported for a conversation, so `onSessionFile` fires when it CHANGES
+     * rather than once per turn. The path is stable for the life of a session; what changes it is a
+     * rebuild (a revert, an eviction, a fingerprint change), which is exactly when the cached locator
+     * needs refreshing.
+     */
+    reportedSessionFiles = new Map();
     /**
      * `steer` commands written to a child and not yet answered by Pi, keyed by the command id.
      *
@@ -305,6 +301,8 @@ export class PiRpcRuntime {
     pendingCatalogs = new Map();
     /** Latches the "no extension on disk" warning, so it is said once rather than once per turn. */
     warnedMissingExtension = false;
+    /** Latches the "Pi's SDK is not installed" warning, for the same reason. */
+    warnedMissingSdk = false;
     /**
      * 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
@@ -318,6 +316,13 @@ export class PiRpcRuntime {
      */
     pi;
     canSteer(conversationId) {
+        // A steer is only meaningful while a turn is RUNNING. A live session with nothing running is not a
+        // steer target: there is no current answer for the message to be inserted into, and the transcript's
+        // split-on-delivery model would have nothing to split. So this asks about the TURN, not about the
+        // process - which is the change the persistent session forces, and the reason it is stated here
+        // rather than left to a caller that used to infer it from a live child.
+        if (this.activeTurns.has(conversationId))
+            return true;
         const run = this.runs.get(conversationId);
         return Boolean(run && run.child.exitCode === null && !run.child.killed && !run.child.stdin.destroyed);
     }
@@ -347,6 +352,10 @@ export class PiRpcRuntime {
      * 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.
+     *
+     * `sessionFactory` is the TEST SEAM for the session path: the pool builds sessions through it instead
+     * of `createPiSession`, so a test can drive `answer()` against a fake `PiSessionLike` and assert on
+     * what the turn did with it - the same role the factory parameter plays in `PiSessionPool` itself.
      */
     options = {}) {
         this.sessionDir = sessionDir;
@@ -355,6 +364,59 @@ export class PiRpcRuntime {
         this.pi = resolvePiCommand({ command });
         if (!this.pi.found)
             console.warn(`PiRpcRuntime: ${this.pi.reason}`);
+        this.sessionPool = new PiSessionPool(sessionDir, repositoryRootFrom(), undefined, (conversationId) => {
+            // A session's credential dies with the session. The session is what HELD the token - its
+            // extension read it out of the environment when it was loaded - so a session that is gone must
+            // not leave a usable token behind.
+            releaseCapability(conversationId);
+            // The session also held this conversation's UI bridge and session-file cache; both are facts
+            // ABOUT that session and stop being true with it.
+            this.sessionHosts.delete(conversationId);
+            this.reportedSessionFiles.delete(conversationId);
+        }, options.sessionFactory ?? createPiSession, (conversationId) => mintCapability(conversationId));
+    }
+    /**
+     * The configuration of the session that was built for a conversation, for tests to inspect.
+     *
+     * WHY THIS EXISTS. The permission boundary - an agent's tool allowlist, its prompt file, the
+     * extensions it mounts - used to be proved by reading the ARGV of a spawned child. A session is not
+     * a child and has no argv, so the evidence moved: this is what the session was actually BUILT with,
+     * which is the same fact stated in the new architecture's terms.
+     *
+     * It is a RECORD, not a control channel: nothing in the runtime reads it back, and a test that
+     * asserts on it is asserting on the real decision the real code made.
+     */
+    builtSessions = new Map();
+    /** The configuration a conversation's session was built with, if one was built. */
+    builtSessionConfig(conversationId) {
+        return this.builtSessions.get(conversationId);
+    }
+    /**
+     * Whether the SDK-backed session layer can be used at all.
+     *
+     * The SDK is a LIBRARY and it is optional: Super Pi also supports running against a Pi installed as a
+     * COMMAND, and a server that cannot load the library still has a working one-shot path for the
+     * conversations it can serve. The answer is reported rather than thrown, so the caller can say what is
+     * missing instead of failing a turn with a stack trace.
+     */
+    async sessionSupport() {
+        return piSdkAvailable();
+    }
+    /**
+     * Throws away every live session.
+     *
+     * Called at shutdown, and after a `revert` - the transcript on disk changed, and a session holding
+     * the old context in memory would keep answering from history the user has withdrawn.
+     */
+    async disposeSessions(conversationId) {
+        if (conversationId)
+            await this.sessionPool.evict(conversationId);
+        else
+            await this.sessionPool.disposeAll();
+    }
+    /** Throws away the sessions that have been idle for a while. */
+    async evictIdleSessions() {
+        await this.sessionPool.evictIdle();
     }
     /**
      * The agent a conversation runs as, or undefined for Pi's own defaults.
@@ -417,11 +479,18 @@ export class PiRpcRuntime {
      * 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.
      */
+    /**
+     * The environment Super Pi's extensions read when they are loaded.
+     *
+     * IT DOES NOT INCLUDE THE CREDENTIAL. The credential is minted by the session pool, when the session
+     * is created, and added there - because the credential belongs to the SESSION (the extension reads
+     * its environment once, when it is loaded) and a token minted per turn would be replaced before the
+     * second turn of the conversation, leaving the extension holding a value the server had forgotten.
+     */
     async taskExtensionEnv(conversationId) {
         const { agents, problems } = await readAgents(this.agents.dir, { mode: "subagent" });
         for (const problem of problems)
             console.warn(`PiRpcRuntime: ${problem.file} is not a usable sub-agent - ${problem.message}`);
-        const capability = mintCapability(conversationId);
         return {
             [TASK_ENDPOINT_ENV]: this.options.endpoint ?? "",
             [TASK_EXEC_ENDPOINT_ENV]: this.options.execEndpoint ?? "",
@@ -432,15 +501,460 @@ export class PiRpcRuntime {
             [WORKFLOW_ENDPOINT_ENV]: this.options.workflowEndpoint ?? "",
             SUPER_PI_QUESTION_ENDPOINT: this.options.questionEndpoint ?? "",
             SUPER_PI_TOOLS_ENDPOINT: this.options.toolsEndpoint ?? "",
-            SUPER_PI_TOOLS_CAPABILITY: capability,
-            // MINTED HERE, AT SPAWN, rather than read from anywhere: this is the only moment the value is
-            // decided, so it cannot change underneath a running child. `SubagentSupervisor` never calls this
-            // function, so no sub-agent process is ever handed a capability - which is what makes a sub-agent
-            // unable to dispatch, however its allowlist is broken.
+        };
+    }
+    /**
+     * The environment for a ONE-SHOT child, which is the same as the session's except that it carries
+     * the credential.
+     *
+     * THE DIFFERENCE IS THE LIFETIME. A one-shot child lives for one turn, so its credential is minted
+     * for that turn and dies with the child - which is the original rule, and it is still exactly right
+     * here. A session lives for many turns, so its credential is minted when the session is created (see
+     * `PiSessionPool.acquire`) and the server separately requires a running turn for it to be usable.
+     */
+    async oneShotExtensionEnv(conversationId) {
+        const capability = mintCapability(conversationId);
+        return {
+            ...(await this.taskExtensionEnv(conversationId)),
             [TASK_CAPABILITY_ENV]: capability,
+            SUPER_PI_TOOLS_CAPABILITY: capability,
+        };
+    }
+    /**
+     * RUNS A TURN ON A PERSISTENT SESSION.
+     *
+     * This is the path every conversation takes now, and it is where the latency win comes from. There is
+     * no process to spawn and none to kill: the conversation's session already exists, its context is
+     * already in memory, and a turn is a `prompt()` on it. An interrupt is `abort()` on the same session -
+     * which is why an interrupt no longer costs a process teardown and a process startup.
+     *
+     * THE EVENT ROUTING. Pi pushes events through a subscription; this method pulls them, one at a time,
+     * through a queue. The generator yields text deltas to its caller, and every non-text event is
+     * delivered to the turn's callbacks as it arrives, so the transcript shows tool calls and reasoning
+     * WHILE the model is producing them rather than after the turn ends.
+     *
+     * THE ABORT. The caller's `signal` is the turn's abort. When it fires, the session is aborted - Pi
+     * stops the current operation and waits for the session to go idle - and the turn ends. The session
+     * ITSELF survives: it is the next turn's session, and it is the reason the next turn costs no startup.
+     */
+    /**
+     * The configuration a conversation's session is built with.
+     *
+     * SEPARATED FROM THE BUILD ON PURPOSE, because this is a decision and the build is its consequence.
+     * Everything that decides what Pi is allowed to do for a conversation - the agent's allowlist, its
+     * prompt file, the extensions it mounts, the model it runs on - is decided HERE, in one place, and
+     * the session is then built from it.
+     *
+     * Two things want that separation. The FIRST is the fingerprint: the decision is what the session is
+     * compared against, so a changed decision means the session is stale. The SECOND is the tests: the
+     * permission boundary is the most important thing this runtime does, and asserting on the decision
+     * is a DIRECT way to check it - a test that has to start a real Pi to learn what Pi was told is a
+     * test that only runs on a machine with a Pi.
+     */
+    async sessionConfiguration(conversation, cwd) {
+        // The agent definition, read from disk EVERY turn. That freshness is the whole point of the
+        // fingerprint: an edited agent file changes the configuration, the session is replaced, and the
+        // edit takes effect on the next message with no restart and no re-selection.
+        const agent = await this.agentFor(conversation);
+        // The SDK path has no RPC `get_state` round trip before its first prompt. Preserve the old guard at
+        // the equivalent boundary: before a session is created. In particular, an unspecified conversation
+        // model means "the catalog's Pi default", which still has to pass the workspace policy.
+        if (agent?.model)
+            await this.modelValidator?.(conversation.id, { ...agent.model, label: agent.model.modelId });
+        await this.modelValidator?.(conversation.id, conversation.model);
+        // The tool selection and the prompt file are the SAME DECISION the spawn line used to carry, in the
+        // form the SDK takes. `toolSelection` is the shared translation, so an agent that declares
+        // `tools: {"*": false, "read": true}` gets exactly the same tools here as it used to get on the
+        // command line - including the empty allowlist that means "this agent talks and does not act".
+        const selection = agent
+            ? toolSelection(agent.tools, { extraAllowedTools: this.extensionToolNames() })
+            : {};
+        const systemPromptFile = agent ? await writeAgentPrompt(this.agents.promptDir, agent) : undefined;
+        return {
+            ...(selection.tools ? { tools: selection.tools } : {}),
+            ...(selection.excludeTools ? { excludeTools: selection.excludeTools } : {}),
+            ...(systemPromptFile ? { systemPromptFile } : {}),
+            ...(agent?.promptMode ? { systemPromptMode: agent.promptMode } : {}),
+            extensionPaths: superPiExtensionPaths(repositoryRootFrom()),
+            extensionEnv: await this.taskExtensionEnv(conversation.id),
+            ...(conversation.model ? { model: { provider: conversation.model.provider, modelId: conversation.model.modelId } } : {}),
+            ...(conversation.thinkingLevel ? { thinkingLevel: conversation.thinkingLevel } : {}),
+        };
+    }
+    async *answerOnSession(input) {
+        const { conversation, prompt, signal, cwd, images } = input;
+        const latencyStartedAt = performance.now();
+        traceLatency(conversation.id, "session.begin", latencyStartedAt);
+        const configuration = await this.sessionConfiguration(conversation, cwd);
+        // The record of what this session is built with. Written BEFORE the session is acquired, so it
+        // exists even when the build fails - a test that wants to know what Super Pi INTENDED to give Pi
+        // must be able to ask after a failure too.
+        this.builtSessions.set(conversation.id, configuration);
+        const session = await this.sessionPool.acquire({
+            conversationId: conversation.id,
+            cwd: resolve(cwd),
+            agentId: conversation.agentId ?? null,
+            extensionEnv: configuration.extensionEnv,
+            ...(configuration.tools ? { tools: configuration.tools } : {}),
+            ...(configuration.excludeTools ? { excludeTools: configuration.excludeTools } : {}),
+            ...(configuration.systemPromptFile ? { systemPromptFile: configuration.systemPromptFile } : {}),
+            ...(configuration.systemPromptMode ? { systemPromptMode: configuration.systemPromptMode } : {}),
+            ...(configuration.model ? { model: configuration.model } : {}),
+            ...(configuration.thinkingLevel ? { thinkingLevel: configuration.thinkingLevel } : {}),
+        });
+        traceLatency(conversation.id, "session.acquired", latencyStartedAt);
+        // THE SESSION-FILE LOCATOR. `revert` and `fork` open the conversation's transcript by PATH, and the
+        // path is a fact the session already knows: its SessionManager resolves it at creation, before any
+        // byte is written. Reported when it CHANGES rather than once per turn - the path is stable for the
+        // life of a session, and a rebuild (revert, eviction, fingerprint change) is exactly when the cached
+        // locator needs refreshing. Best-effort, like the RPC path's get_state read: a failed report must not
+        // fail the turn, it only means the next revert pays for the spawn fallback.
+        if (input.onSessionFile && typeof session.sessionFile === "string" && session.sessionFile
+            && this.reportedSessionFiles.get(conversation.id) !== session.sessionFile) {
+            try {
+                await input.onSessionFile(session.sessionFile);
+                this.reportedSessionFiles.set(conversation.id, session.sessionFile);
+            }
+            catch (error) {
+                console.warn(`PiRpcRuntime: could not record the session file of conversation ${conversation.id} (${error instanceof Error ? error.message : "unknown error"}) - the next revert will locate it the slow way.`);
+            }
+        }
+        // THE EXTENSION-UI BRIDGE, bound ONCE per session. Pi's extensions ask their blocking questions
+        // through the session's UI context, which starts life as a no-op that silently answers
+        // `undefined`/`false` - and for `confirm` a silent `false` is a fabricated "no" the user never gave.
+        // The bridge forwards to the host of whichever turn is running RIGHT NOW (registered below), and
+        // answers `cancelled` when there is none - the same rule the RPC path's no-host branch follows.
+        if (session.extensionRunner && !this.uiBoundSessions.has(session)) {
+            this.uiBoundSessions.add(session);
+            try {
+                session.extensionRunner.setUIContext(this.extensionUiBridge(conversation.id), "rpc");
+            }
+            catch (error) {
+                console.warn(`PiRpcRuntime: could not bind the extension UI bridge for conversation ${conversation.id}: ${error instanceof Error ? error.message : "unknown error"}. Pi extensions that ask questions will get cancelled answers.`);
+            }
+        }
+        if (input.host)
+            this.sessionHosts.set(conversation.id, input.host);
+        // WHERE THIS TURN STARTS in Pi's own transcript, captured BEFORE the prompt. The one-shot path asked
+        // Pi over RPC (`get_entries` for the leaf, then `get_entries(since: leaf)` after the turn); a live
+        // session holds the same entries in memory, so the same two reads are synchronous. `null` is a real
+        // answer - an empty session, so the whole branch is this turn's; `undefined` means the session has no
+        // transcript to read (a test double), and nothing is recorded.
+        const transcript = session.sessionManager;
+        let turnStartLeaf;
+        if (input.onUserEntry && transcript) {
+            try {
+                turnStartLeaf = transcript.getLeafId();
+            }
+            catch (error) {
+                console.warn(`PiRpcRuntime: could not read the leaf before the turn of conversation ${conversation.id} (${error instanceof Error ? error.message : "unknown error"}) - this turn's message may not become a revert boundary.`);
+            }
+        }
+        const queue = new TurnQueue();
+        const handlers = {
+            onToolCall: input.onToolCall,
+            onToolUpdate: input.onToolUpdate,
+            onToolPreparing: input.onToolPreparing,
+            onToolEnd: input.onToolEnd,
+            onThinking: input.onThinking,
+            onThinkingEnd: input.onThinkingEnd,
+            onSteerDelivered: input.onSteerDelivered,
+            onPiQueue: input.onPiQueue,
+        };
+        const announced = new Set();
+        const report = (key) => {
+            if (announced.has(key))
+                return;
+            announced.add(key);
+            console.warn(`PiRpcRuntime: unhandled Pi session event ${key} - consumed without action.`);
+        };
+        const unsubscribe = session.subscribe((event) => {
+            try {
+                handleSessionEvent(event, queue, handlers, report);
+            }
+            catch (error) {
+                console.warn(`PiRpcRuntime: the session event handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
+            }
+        });
+        // The abort. The caller's signal is the turn's, and aborting the session is what makes the model
+        // stop. The session is NOT destroyed: it is the next turn's session.
+        //
+        // The turn has its OWN controller, and the caller's signal aborts it. A run can span several turns
+        // on one session, so "the caller wants this run to stop" and "Pi has to be told about the turn in
+        // flight" are two different facts, and only the second one is Pi's business.
+        //
+        // `abortDone` is the abort's OWN promise, kept so `stop()` can await Pi actually going idle rather
+        // than merely having been ASKED to. `AgentSession.abort()` resolves when the session is idle, which
+        // is the fact an interrupt needs before the next prompt: prompting earlier is refused by Pi with
+        // "Agent is already processing".
+        const turnController = new AbortController();
+        let abortDone = Promise.resolve();
+        const abortTurn = () => {
+            if (turnController.signal.aborted)
+                return;
+            turnController.abort();
+            abortDone = session.abort().catch((error) => {
+                console.warn(`PiRpcRuntime: aborting the session of ${conversation.id} threw: ${error instanceof Error ? error.message : "unknown error"}`);
+            });
+        };
+        const onAbort = () => { abortTurn(); };
+        if (signal.aborted)
+            abortTurn();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+        let firstTextSeen = false;
+        const finished = (async () => {
+            try {
+                await session.prompt(prompt, images?.length ? { images: images } : undefined);
+                traceLatency(conversation.id, "session.prompt.accepted", latencyStartedAt);
+                // `prompt()` RETURNING IS NOT THE TURN ENDING. Pi's `prompt` resolves when the message has
+                // been ACCEPTED and the run has been started; the agent is still streaming, still executing
+                // tools, still settling. A turn that ended here would release the reader while the model was
+                // still producing, and the NEXT turn would arrive at a session Pi considers busy - which Pi
+                // refuses with "Agent is already processing".
+                //
+                // The turn's end is the `agent_settled` EVENT, and the queue is what carries it: the bridge
+                // pushes the terminal item when Pi settles, and the consumer below reads it. This promise
+                // waits for that signal, and the race with the prompt's own failure is what keeps a turn that
+                // never settles from hanging forever - a hung turn is a conversation that never answers.
+                await Promise.race([
+                    queue.settledSignal,
+                    // The safety net. A session that was aborted, or a Pi that died mid-turn, may never settle,
+                    // and the turn still has to end - otherwise the conversation is stuck on a turn that will
+                    // never produce anything and the next message can never be sent.
+                    new Promise((resolvePromise) => setTimeout(resolvePromise, 5_000)),
+                ]);
+                traceLatency(conversation.id, "session.settled", latencyStartedAt);
+                // THE REVERT BOUNDARY, recorded at the same moment the one-shot path records it: the turn has
+                // settled, so every entry this turn wrote - the user message included - is in the transcript.
+                // Recorded on abort too, on purpose: an aborted turn still PERSISTED the user message, and a
+                // message in the transcript with no recorded id is a message the user can see but never revert
+                // to. A prompt that was never accepted wrote nothing, so there is nothing to find.
+                if (transcript && turnStartLeaf !== undefined && input.onUserEntry) {
+                    await this.recordSessionTurnEntryId(transcript, turnStartLeaf, conversation.id, input.onUserEntry);
+                }
+            }
+            catch (error) {
+                queue.fail(error instanceof Error ? error : new Error(String(error)));
+            }
+        })();
+        this.activeTurns.set(conversation.id, { queue, unsubscribe, finished, abort: abortTurn, get abortDone() { return abortDone; } });
+        try {
+            for (;;) {
+                const item = await queue.next();
+                if (item.kind === "text") {
+                    if (!firstTextSeen) {
+                        firstTextSeen = true;
+                        traceLatency(conversation.id, "session.first-text", latencyStartedAt);
+                    }
+                    yield item.delta;
+                    continue;
+                }
+                if (item.kind === "error")
+                    throw item.error;
+                break;
+            }
+        }
+        finally {
+            signal.removeEventListener("abort", onAbort);
+            unsubscribe();
+            this.activeTurns.delete(conversation.id);
+            // The host registration belongs to THIS turn: an extension question that arrives after it ends
+            // finds no host and is answered `cancelled`, which is the honest answer to "nobody is being asked".
+            if (input.host)
+                this.sessionHosts.delete(conversation.id);
+            await finished.catch(() => undefined);
+        }
+    }
+    /**
+     * The Extension UI context a session's extensions talk to, bridged to the host of the turn that is
+     * running right now.
+     *
+     * THE SHAPES MIRROR PI'S OWN RPC UI CONTEXT (rpc-mode.ts), method for method, because the extensions
+     * were written against that contract: `select`/`input`/`editor` resolve to the chosen text or
+     * `undefined` on cancel, `confirm` resolves to a boolean with cancel reading as `false` (Pi's own
+     * mapping, not an invention), and the one-way methods are fire-and-forget. The TUI-only methods
+     * (`setWorkingMessage`, footers, headers, `custom`, ...) are the same no-ops they are in RPC mode.
+     *
+     * A BLOCKING CALL WITH NO HOST IS CANCELLED, NEVER DEFAULTED. The no-op context Pi starts with answers
+     * `confirm` with `false`, which is indistinguishable from the user clicking "no" - the exact failure
+     * the "cancelled, never a default" rule exists to prevent. So an idle session (no turn, no host) and a
+     * failed host both answer `cancelled`, and the reason is logged.
+     */
+    extensionUiBridge(conversationId) {
+        const ask = async (request) => {
+            const host = this.sessionHosts.get(conversationId);
+            if (!host) {
+                console.warn(`PiRpcRuntime: an extension asked ${request.method} on conversation ${conversationId} with no turn running - cancelled rather than answering on the user's behalf.`);
+                return { cancelled: true };
+            }
+            try {
+                return await host.ask({ ...request, requestId: randomUUID(), blocking: true });
+            }
+            catch (error) {
+                console.warn(`PiRpcRuntime: the UI host failed a ${request.method} for conversation ${conversationId} (${error instanceof Error ? error.message : "unknown error"}) - cancelled.`);
+                return { cancelled: true };
+            }
         };
+        const notify = (request) => {
+            try {
+                this.sessionHosts.get(conversationId)?.notify({ ...request, requestId: randomUUID(), blocking: false });
+            }
+            catch (error) {
+                console.warn(`PiRpcRuntime: the UI host threw on a ${request.method} notification for conversation ${conversationId}: ${error instanceof Error ? error.message : "unknown error"}`);
+            }
+        };
+        /** Pi passes its dialog timeout straight through; `ExtensionUiRequest.timeoutMs` is the same number. */
+        const timeoutOf = (opts) => {
+            const timeout = opts?.timeout;
+            return typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0 ? { timeoutMs: timeout } : {};
+        };
+        return {
+            select: async (title, options, opts) => {
+                const answer = await ask({ method: "select", title: typeof title === "string" ? title : "", options: Array.isArray(options) ? options.filter((item) => typeof item === "string") : [], ...timeoutOf(opts) });
+                return answer.cancelled ? undefined : answer.value;
+            },
+            confirm: async (title, message, opts) => {
+                const answer = await ask({ method: "confirm", title: typeof title === "string" ? title : "", message: typeof message === "string" ? message : "", ...timeoutOf(opts) });
+                return answer.cancelled ? false : answer.confirmed === true;
+            },
+            input: async (title, placeholder, opts) => {
+                const answer = await ask({ method: "input", title: typeof title === "string" ? title : "", ...(typeof placeholder === "string" ? { placeholder } : {}), ...timeoutOf(opts) });
+                return answer.cancelled ? undefined : answer.value;
+            },
+            editor: async (title, prefill) => {
+                const answer = await ask({ method: "editor", title: typeof title === "string" ? title : "", ...(typeof prefill === "string" ? { prefill } : {}) });
+                return answer.cancelled ? undefined : answer.value;
+            },
+            notify: (message, type) => notify({ method: "notify", title: "", message: typeof message === "string" ? message : "", notifyType: (type === "warning" || type === "error" ? type : "info") }),
+            onTerminalInput: () => () => { },
+            setStatus: (key, text) => notify({ method: "setStatus", title: "", statusKey: typeof key === "string" ? key : "", ...(typeof text === "string" ? { statusText: text } : {}) }),
+            setWidget: (key, content, options) => {
+                if (content !== undefined && !Array.isArray(content))
+                    return; // component factories need the TUI
+                const placement = options?.placement;
+                notify({ method: "setWidget", title: "", widgetKey: typeof key === "string" ? key : "", ...(Array.isArray(content) ? { widgetLines: content.filter((line) => typeof line === "string") } : {}), ...(placement === "aboveEditor" || placement === "belowEditor" ? { widgetPlacement: placement } : {}) });
+            },
+            setTitle: (title) => notify({ method: "setTitle", title: typeof title === "string" ? title : "" }),
+            setEditorText: (text) => notify({ method: "set_editor_text", title: "", ...(typeof text === "string" ? { text } : {}) }),
+            pasteToEditor: (text) => notify({ method: "set_editor_text", title: "", ...(typeof text === "string" ? { text } : {}) }),
+            // The rest need the TUI or have no web meaning; they are the same no-ops RPC mode provides.
+            setWorkingMessage: () => { },
+            setWorkingVisible: () => { },
+            setWorkingIndicator: () => { },
+            setHiddenThinkingLabel: () => { },
+            setFooter: () => { },
+            setHeader: () => { },
+            custom: async () => undefined,
+            getEditorText: () => "",
+            addAutocompleteProvider: () => { },
+            setEditorComponent: () => { },
+            getEditorComponent: () => undefined,
+        };
+    }
+    /**
+     * Records the id of the user message this turn wrote, read from the live session's own transcript.
+     *
+     * THE SAME CONTRACT AS `recordTurnEntryId` ON THE ONE-SHOT PATH, over memory instead of RPC: the
+     * captured pre-turn leaf is what makes the read exact, because the entries written after it belong to
+     * THIS turn, and the first USER message among them is the one Super Pi just pushed. The three outcomes
+     * are the same three:
+     *
+     * - leaf `null` - the session was empty, so the whole branch is this turn's.
+     * - leaf found in the branch - everything after it is this turn's.
+     * - leaf NOT found - the transcript moved underneath us (a compaction rewrite, a branch switch), so
+     *   nothing can be attributed to this turn with certainty and nothing is recorded. Guessing here would
+     *   hand back an EARLIER turn's id, and a revert to it would silently cut more than the user asked for.
+     *
+     * Every failure is a warning, never a throw: the answer has already streamed by this point, and "this
+     * message cannot be a revert boundary" is not "your message failed".
+     */
+    async recordSessionTurnEntryId(transcript, leaf, conversationId, onUserEntry) {
+        try {
+            const branch = transcript.getBranch();
+            let startIndex = 0;
+            if (leaf !== null) {
+                const at = branch.findIndex((entry) => entry?.id === leaf);
+                if (at === -1) {
+                    console.warn(`PiRpcRuntime: the entry this turn started from is no longer in the transcript of conversation ${conversationId}, so its message was not recorded and cannot be used as a revert boundary.`);
+                    return;
+                }
+                startIndex = at + 1;
+            }
+            const firstUser = branch.slice(startIndex).find((entry) => {
+                const candidate = entry;
+                return candidate?.type === "message" && candidate.message?.role === "user" && typeof candidate.id === "string";
+            });
+            if (!firstUser) {
+                console.warn(`PiRpcRuntime: the entries this turn of conversation ${conversationId} wrote contain no user message, so nothing was recorded as a revert boundary.`);
+                return;
+            }
+            await onUserEntry(firstUser.id);
+        }
+        catch (error) {
+            console.warn(`PiRpcRuntime: could not record this turn's Pi entry id for conversation ${conversationId} (${error instanceof Error ? error.message : "unknown error"}) - its message cannot be used as a revert boundary.`);
+        }
+    }
+    /**
+     * The tool names Super Pi's own extensions contribute, for the agent's allowlist.
+     *
+     * The same list the spawn line used to carry, so an agent that declares `tools: {"*": false, "read":
+     * true}` gets exactly the same tools it used to get - and an agent that says `task: false` still wins,
+     * because `toolFlags` treats an explicit false as outranking a host extra.
+     */
+    extensionToolNames() {
+        const names = [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, "question", "tool_register"];
+        if (this.memory)
+            names.push("memory", "skill_manage", "session_search");
+        if (this.knowledge)
+            names.push(KNOWLEDGE_TOOL_NAME);
+        return names;
+    }
+    async *answer(input) {
+        // The one-shot paths keep their own child process, and they are NOT the same thing as a conversation
+        // turn: a memory review and a knowledge reranker have their own ids, their own tool sets and their own
+        // lifetimes, and folding them into a conversation's session would give them that conversation's
+        // context. They are identified by the flags that describe exactly that.
+        if (input.memoryReview || input.knowledgeRerank) {
+            yield* this.answerOneShot(input);
+            return;
+        }
+        // AN EXPLICITLY NAMED PI MEANS THE ONE-SHOT PATH, and this is a rule about the user's CONFIGURATION
+        // rather than about speed.
+        //
+        // `SUPER_PI_PI_COMMAND` says "use THIS Pi". The session path does not use a Pi command at all: it
+        // imports Pi as a library, and the library it imports is the one installed next to Super Pi. So a
+        // server configured with an explicit command would silently ignore it - the user would point Super Pi
+        // at one Pi and get a different one, with nothing saying so.
+        //
+        // A named command is therefore honoured: the child process IS that command, and the one-shot path is
+        // the only path that can promise that. This also keeps the test suite's fake Pi meaningful, because
+        // a test that names a fake Pi is naming a program that speaks the RPC protocol, not a library.
+        if (this.pi.found && this.pi.explicit) {
+            yield* this.answerOneShot(input);
+            return;
+        }
+        // The main path: a persistent session, reused across turns. When the SDK cannot be loaded the turn
+        // falls back to the one-shot path rather than failing, and the reason is reported once - a server
+        // that cannot use the SDK still serves conversations, just at the old speed.
+        const support = await this.sessionSupport();
+        if (!support.available) {
+            if (!this.warnedMissingSdk) {
+                this.warnedMissingSdk = true;
+                console.warn(`PiRpcRuntime: ${support.reason} Falling back to one-shot Pi processes for conversations.`);
+            }
+            yield* this.answerOneShot(input);
+            return;
+        }
+        yield* this.answerOnSession(input);
     }
-    async *answer({ conversation, prompt, signal, cwd, host, onPiQueue, onSteerDelivered, onUserEntry, onSessionFile, onToolCall, onToolUpdate, onToolPreparing, onToolEnd, onThinking, onThinkingEnd, images, memoryReview, memorySourceConversationId, knowledgeRerank }) {
+    /**
+     * The one-shot path: a fresh child process for a single turn.
+     *
+     * Still used for the memory review, the knowledge reranker, and as the fallback when Pi's SDK is not
+     * installed. The main conversation path does NOT come here - see `answer`.
+     */
+    async *answerOneShot({ conversation, prompt, signal, cwd, host, onPiQueue, onSteerDelivered, onUserEntry, onSessionFile, onToolCall, onToolUpdate, onToolPreparing, onToolEnd, onThinking, onThinkingEnd, images, memoryReview, memorySourceConversationId, knowledgeRerank }) {
         const latencyStartedAt = performance.now();
         traceLatency(conversation.id, "answer.begin", latencyStartedAt);
         await mkdir(this.sessionDir, { recursive: true });
@@ -515,7 +1029,7 @@ export class PiRpcRuntime {
             // every turn would silently replace the child's environment with whatever THIS process has at
             // spawn time. Inheriting is what an omitted `env` already does, so the two paths differ in nothing
             // but the four documented additions.
-            ...((extensionArgs.length || memoryEnabled || knowledgeEnabled) ? { env: { ...process.env, ...(extensionArgs.length ? await this.taskExtensionEnv(conversation.id) : {}), ...(memoryEnabled ? {
+            ...((extensionArgs.length || memoryEnabled || knowledgeEnabled) ? { env: { ...process.env, ...(extensionArgs.length ? await this.oneShotExtensionEnv(conversation.id) : {}), ...(memoryEnabled ? {
                         SUPER_PI_MEMORY_ENDPOINT: process.env.SUPER_PI_MEMORY_ENDPOINT,
                         SUPER_PI_MEMORY_TOKEN: memoryToken,
                         SUPER_PI_MEMORY_REVIEW: memoryReview ? "1" : "0",
@@ -928,9 +1442,10 @@ export class PiRpcRuntime {
         finally {
             signal.removeEventListener("abort", abort);
             this.runs.delete(conversation.id);
-            // The capability dies with the turn that was given it. In this `finally`, so it happens on every
+            // The capability dies with the CHILD that was given it. In this `finally`, so it happens on every
             // exit - a turn that answered, a turn that threw, and a turn whose child was killed - because a
-            // credential whose turn has ended is a credential with no owner.
+            // credential whose process has ended is a credential with no owner. The one-shot path is the only
+            // place this still holds literally: on the session path the child does not die with the turn.
             releaseCapability(conversation.id);
             if (memoryToken)
                 this.memory?.release(memoryToken);
@@ -1056,7 +1571,7 @@ export class PiRpcRuntime {
      * elimination of an entire class of "we truncated the wrong file and nothing said so" failures.
      */
     async revert({ conversation, cwd, boundaryEntryId, beforeBoundary }) {
-        if (this.runs.has(conversation.id))
+        if (this.runs.has(conversation.id) || this.activeTurns.has(conversation.id))
             throw new Error("这个会话还有一轮任务在跑，先停止它再回退");
         if (!this.pi.found)
             throw new Error(this.pi.reason);
@@ -1069,6 +1584,14 @@ export class PiRpcRuntime {
             const exists = await stat(cached).catch(() => undefined);
             if (exists?.isFile()) {
                 const result = await truncateSessionFile(cached, boundaryEntryId, conversation.id, beforeBoundary);
+                // THE SESSION MUST GO. The truncation above changed the transcript ON DISK, and a live session
+                // holds the OLD context in memory. Nothing in Pi would notice the difference: the model would
+                // keep answering from history the user has just withdrawn, while `state.json` and the file on
+                // disk both said it was gone. Three views of the conversation, two of them wrong, and no error
+                // anywhere - so the session is destroyed here and the next turn rebuilds it from the truncated
+                // file. This is the one place where eviction is a correctness requirement and not an
+                // optimization.
+                await this.sessionPool.evict(conversation.id);
                 return { sessionFile: cached, linesKept: result.linesKept, entriesDropped: result.entriesDropped };
             }
         }
@@ -1285,6 +1808,21 @@ export class PiRpcRuntime {
         reply(buildExtensionUiResponse(request, answer));
     }
     async stop(conversationId) {
+        // A turn on a persistent session is stopped by aborting THAT SESSION, and the session survives - it
+        // is the next turn's session. This is the whole reason an interrupt no longer costs a process
+        // teardown and a process startup: there is no process to tear down.
+        const turn = this.activeTurns.get(conversationId);
+        if (turn) {
+            turn.abort();
+            // WAIT FOR PI TO ACTUALLY GO IDLE, not merely to have been asked. `AgentSession.abort()` resolves
+            // when the session is idle, and idle is the fact the caller needs: an interrupt that starts the
+            // next turn before this one has unwound is refused by Pi with "Agent is already processing". The
+            // backstop keeps a wedged session from hanging a stop forever - the turn's own 5s safety net then
+            // still ends it.
+            await Promise.race([turn.abortDone, new Promise((resolvePromise) => setTimeout(resolvePromise, 5_000))]);
+            return;
+        }
+        // The one-shot path: a child process that has to be told to abort over its stdin.
         const run = this.runs.get(conversationId);
         if (!run)
             return;
@@ -1441,7 +1979,43 @@ export class PiRpcRuntime {
                 await killTree(child.pid);
         }
     }
+    /**
+     * The live session for a conversation, if there is one.
+     *
+     * Throws when there is none, because every caller wants a session it can act on - a steer that has
+     * nowhere to go is a refusal the caller turns into "this message could not be delivered", not a
+     * silent success.
+     */
+    async sessionFor(conversationId) {
+        const session = this.sessionPool.get(conversationId);
+        if (!session)
+            throw new SteerUnavailableError(`会话 ${conversationId} 还没有可用的 Pi 会话`);
+        return session;
+    }
     async steer(conversationId, message, images) {
+        // THE SESSION PATH. A steer on a persistent session is a `prompt` with `streamingBehavior:
+        // "steer"` - the same queueing semantics Pi's RPC `steer` command has, expressed the way the SDK
+        // takes it. The session is NOT aborted and NOT given a second writer: the message joins the turn
+        // that is already running, and Pi delivers it at the next turn boundary.
+        //
+        // THE DISPOSITION. The SDK does not answer a steer with a disposition the way the RPC command does,
+        // so it is derived from what the SDK can tell us: a steer accepted while a turn is running is
+        // `queued` (Pi will deliver it at the next boundary), and one accepted with nothing running is
+        // `handled`. The distinction is the one the caller needs: a queued message is still cancellable
+        // and has NOT yet reached the model.
+        if (this.activeTurns.has(conversationId)) {
+            const session = await this.sessionFor(conversationId);
+            const imagePayloads = this.options.uploadsDir && images?.length
+                ? await loadConversationImages(this.options.uploadsDir, conversationId, images)
+                : undefined;
+            try {
+                await session.prompt(message, { ...(imagePayloads ? { images: imagePayloads } : {}), streamingBehavior: "steer" });
+            }
+            catch (error) {
+                throw error instanceof Error ? error : new Error(String(error));
+            }
+            return "queued";
+        }
         const run = this.runs.get(conversationId);
         if (!run || !this.canSteer(conversationId))
             throw new SteerUnavailableError(`会话 ${conversationId} 的 Pi 进程已结束`);