@evandu/super-pi 0.1.94 → 0.1.96

package/dist/server/pi-session.js

@@ -0,0 +1,226 @@
+/**
+ * THE SESSION LAYER: one Pi session per Super Pi conversation, alive across turns.
+ *
+ * WHY THIS FILE EXISTS. Super Pi used to spawn a fresh `pi --mode rpc` process for every turn and kill
+ * it when the turn ended. That cost ~400ms of spawn plus ~380ms of handshake plus a full replay of the
+ * transcript on EVERY message, and it is why an interrupt had to kill a process and start another one:
+ * the turn and the process were the same thing. Pi's own `abort` takes 147ms and leaves the session
+ * usable, so the process churn was Super Pi's choice, not a property of interrupting.
+ *
+ * Pi's SDK (`@earendil-works/pi-coding-agent`) is the supported way to embed it - Pi's own RPC docs
+ * recommend it for Node applications. A session here is a Pi `AgentSession`: it keeps the conversation
+ * context in memory across turns, and `abort()` returns as soon as the agent is idle.
+ *
+ * WHAT THIS FILE IS NOT. It is not a second runtime. The one-shot paths (memory review, knowledge
+ * rerank, autotitle, tool LLM, catalog probe) keep spawning their own throwaway children, because their
+ * identity, tool set and lifecycle are deliberately different from the primary agent's and sharing a
+ * session with them would be a correctness bug, not an optimization. See `runtime.ts`.
+ *
+ * THE ONE HARD CONSTRAINT. Pi's agent prompt, its tool allowlist and the extensions it mounts are all
+ * decided when the session is CREATED. None of them can be changed on a live session. So a session carries
+ * a FINGERPRINT of everything that was decided at creation, and the caller compares fingerprints: a
+ * change means the session is stale and must be replaced. `revert` is the sharpest case - it truncates
+ * the transcript on disk while the live session still holds the old context in memory, and nothing in Pi
+ * would notice the difference.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+let sdkPromise;
+let sdkFailure;
+async function loadSdk() {
+    if (sdkFailure)
+        throw new Error(sdkFailure);
+    if (!sdkPromise) {
+        // The specifier is assembled at runtime on purpose: a static `import("...")` would be resolved by
+        // the compiler, which would turn a BROKEN INSTALL into a COMPILE ERROR - and the compiler runs
+        // before anything can report the real reason. The name is written out in full here so a reader
+        // can see exactly which package is being loaded.
+        const specifier = ["@earendil-works", "pi-coding-agent"].join("/");
+        sdkPromise = import(/* @vite-ignore */ specifier).then((mod) => mod, (error) => {
+            const reason = error instanceof Error ? error.message : String(error);
+            sdkFailure = `Super Pi could not load Pi's SDK (@earendil-works/pi-coding-agent): ${reason}. Reinstall Super Pi (npm i -g @evandu/super-pi) so that Pi comes with it, or install it next to Super Pi with \`npm install @earendil-works/pi-coding-agent\`.`;
+            throw new Error(sdkFailure);
+        });
+    }
+    return sdkPromise;
+}
+/** Whether the SDK could be loaded. Used by the server to report the reason instead of failing a turn. */
+export async function piSdkAvailable() {
+    try {
+        await loadSdk();
+        return { available: true };
+    }
+    catch (error) {
+        return { available: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * Fingerprints are compared by VALUE, and this is where that comparison is spelled out.
+ *
+ * The array fields are compared as SETS, not sequences: the tool allowlist is a set of names, and a
+ * caller that happens to list them in a different order is asking for the same session, not a new one.
+ * Getting this wrong in the strict direction would throw away a perfectly good session on every turn
+ * (a latency bug that looks like nothing at all), and getting it wrong in the loose direction would keep
+ * a session whose allowlist had genuinely changed (a permission bug). So: order-insensitive, and every
+ * element compared exactly.
+ */
+export function sameFingerprint(a, b) {
+    if (a.cwd !== b.cwd)
+        return false;
+    if (a.agentId !== b.agentId)
+        return false;
+    if (!sameSet(a.tools, b.tools))
+        return false;
+    if (!sameSet(a.excludeTools, b.excludeTools))
+        return false;
+    if (!sameSet(a.extensions, b.extensions))
+        return false;
+    if (a.model?.provider !== b.model?.provider || a.model?.modelId !== b.model?.modelId)
+        return false;
+    if (a.thinkingLevel !== b.thinkingLevel)
+        return false;
+    return true;
+}
+function sameSet(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    if (a.length !== b.length)
+        return false;
+    const left = [...a].sort();
+    const right = [...b].sort();
+    return left.every((item, index) => item === right[index]);
+}
+/**
+ * Runs `work` with the given environment applied, and restores the previous values afterwards.
+ *
+ * The values are applied SYNCHRONOUSLY and the whole of `work` is awaited inside the window, because
+ * the extension factory runs during the loader's reload and reads the environment at that moment. A
+ * concurrent session's environment would otherwise land in the middle of this one.
+ */
+export async function withEnvironment(values, work) {
+    const previous = new Map();
+    for (const [key, value] of Object.entries(values)) {
+        previous.set(key, process.env[key]);
+        process.env[key] = value;
+    }
+    try {
+        return await work();
+    }
+    finally {
+        for (const [key, value] of previous) {
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+    }
+}
+export async function createPiSession(creation) {
+    const sdk = await loadSdk();
+    const agentDir = creation.agentDir ?? defaultAgentDir();
+    return withEnvironment(creation.extensionEnv, async () => {
+        // THE AGENT'S PROMPT. Pi's loader takes the same two shapes the command line took: a `systemPrompt`
+        // that REPLACES Pi's own, and an `appendSystemPrompt` list of files that are ADDED to it. An agent
+        // that says `promptMode: replace` gets the first, and one that says nothing gets the second - the
+        // same two meanings the `--system-prompt` and `--append-system-prompt` flags carried, and the same
+        // distinction: an append keeps Pi's own coding-agent baseline (its tool guidance, its environment
+        // facts) and adds the role on top.
+        const loader = new sdk.DefaultResourceLoader({
+            cwd: creation.cwd,
+            agentDir,
+            ...(creation.extensionPaths.length ? { additionalExtensionPaths: creation.extensionPaths } : {}),
+            ...(creation.systemPromptFile && creation.systemPromptMode === "replace"
+                ? { systemPrompt: creation.systemPromptFile }
+                : creation.systemPromptFile
+                    ? { appendSystemPrompt: [creation.systemPromptFile] }
+                    : {}),
+        });
+        await loader.reload();
+        const sessionManager = creation.persist === false
+            ? sdk.SessionManager.inMemory(creation.cwd, { id: creation.sessionId })
+            : await resolveSessionManager(sdk, creation);
+        const modelRuntime = await sdk.ModelRuntime.create();
+        // THE MODEL IS RESOLVED, NOT PASSED THROUGH. Pi's SDK takes a whole Model object - the provider's
+        // configuration, the endpoint, the capability list - and Super Pi only knows the pair
+        // (provider, modelId) that the picker shows. The runtime is what turns that pair into the object
+        // Pi needs, and it is the same runtime the catalog probe uses, so the model the session runs on is
+        // the model the picker listed.
+        //
+        // A model that cannot be resolved is NOT a reason to fail the session: Pi falls back to its own
+        // default, and the turn still runs. Failing here would turn "the picker showed a model this Pi no
+        // longer has" into a conversation that cannot be sent at all.
+        const model = creation.model
+            ? modelRuntime.getModel?.(creation.model.provider, creation.model.modelId)
+            : undefined;
+        const options = {
+            cwd: creation.cwd,
+            agentDir,
+            modelRuntime,
+            resourceLoader: loader,
+            sessionManager,
+            ...(creation.tools ? { tools: creation.tools } : {}),
+            ...(creation.excludeTools ? { excludeTools: creation.excludeTools } : {}),
+            ...(model ? { model } : {}),
+            ...(creation.thinkingLevel ? { thinkingLevel: creation.thinkingLevel } : {}),
+        };
+        const { session } = await sdk.createAgentSession(options);
+        return session;
+    });
+}
+/**
+ * Resolves the session manager for a conversation: the EXISTING transcript if there is one, a new one
+ * otherwise.
+ *
+ * WHY THIS IS NOT JUST `SessionManager.create`. A conversation's transcript outlives its session - Pi
+ * writes it to a file, and a session that was evicted (idle, or thrown away by a revert) is rebuilt from
+ * that file. So building a session is "reopen the conversation's transcript", and the id is what says
+ * which transcript: Super Pi's conversation id IS the session id, which is what makes `revert` and
+ * `fork` able to find the file without guessing at a filename.
+ *
+ * The existing file is found by EXACT id, not by listing the directory and matching a name. Pi's own
+ * lookup (`SessionManager.findById`) is the authority for that, and it also enforces the rule that
+ * matters here: a session is only found when it was recorded for the SAME working directory. A
+ * conversation whose workspace changed therefore gets a fresh transcript rather than somebody else's.
+ */
+async function resolveSessionManager(sdk, creation) {
+    const existing = sdk.SessionManager.findById(creation.cwd, creation.sessionId, creation.sessionDir);
+    if (existing) {
+        try {
+            return sdk.SessionManager.open(existing, creation.sessionDir, creation.cwd);
+        }
+        catch {
+            // A file that exists but cannot be opened is not a reason to fail the turn: falling through
+            // creates a fresh session, and the reader sees an empty conversation rather than an error. The
+            // alternative - refusing - would make a corrupt file permanently break the conversation.
+        }
+    }
+    return sdk.SessionManager.create(creation.cwd, creation.sessionDir, { id: creation.sessionId });
+}
+/**
+ * Pi's own global configuration directory, when it can be worked out without importing the SDK.
+ *
+ * The SDK's `getAgentDir()` is the authority, but asking it would mean importing the SDK - which this
+ * file goes out of its way not to do for a path it can derive. The derivation is Pi's own default:
+ * `~/.pi/agent`, with the home directory taken from the environment rather than from `os.homedir()`,
+ * because on Windows the two disagree often enough to matter.
+ */
+function defaultAgentDir() {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    return home ? join(home, ".pi", "agent") : join(".pi", "agent");
+}
+/**
+ * The Super Pi extension files, as absolute paths.
+ *
+ * Resolved from the repository root, exactly as `runtime.ts` resolves the `--extension` argument it
+ * passes to a child process: Pi resolves a relative `--extension` against the CONVERSATION's workspace
+ * rather than against the server's directory, so a relative path would find a different file for every
+ * workspace. The SDK takes an absolute path, and this keeps the two paths of the same file.
+ */
+export function superPiExtensionPaths(repositoryRoot) {
+    const paths = [
+        join(repositoryRoot, "agents", "super-pi-task", "index.ts"),
+        join(repositoryRoot, "agents", "super-pi-memory", "index.ts"),
+        join(repositoryRoot, "agents", "super-pi-knowledge", "index.ts"),
+    ];
+    return paths.filter((path) => existsSync(path));
+}

package/dist/server/runtime.d.ts

@@ -3,6 +3,8 @@ export { RpcChannel, type RpcRecord } from "./rpc-channel.js";
 import type { ActiveMemory } from "./active-memory.js";
 import { type KnowledgeBase } from "./knowledge.js";
 export { forkSessionFile, truncateSessionFile } from "./session-repository.js";
+export { describeDeliveredUserMessage, describePiQueue } from "./pi-session-events.js";
+import { type PiSessionFactory } from "./pi-session.js";
 import { type AgentDefinition, type Conversation, type ExtensionUiAnswer, type ExtensionUiRequest, type MessageImage, type ModelCatalog, type ModelOption, type ModelSelection, type PiQueueSnapshot, type ToolCallNotice, type ToolCallPreparing } from "./types.js";
 /**
  * Who answers Pi's Extension UI questions. The runtime never invents an answer: a blocking method
@@ -79,18 +81,24 @@ export interface AnswerInput {
     /**
      * Called ONCE per turn with the Pi entry id of the user message that started it, or never.
      *
-     * This is the whole of Super Pi's ability to name a position inside Pi's transcript, and the window is
-     * one turn long: `answer()` spawns Pi here and kills it in its `finally`, so an id not taken before the
-     * loop ends is not obtainable at all. It is taken from Pi's own `get_entries` (`rpc-mode.ts:636-647`),
-     * not by counting, because Pi writes entry types that are not messages (`model_change`,
-     * `thinking_level_change`, `compaction`, ...) and only Pi knows which line the user message is.
+     * This is the whole of Super Pi's ability to name a position inside Pi's transcript. The one-shot path
+     * reads it over RPC (`get_entries` before the prompt, `get_entries(since: leaf)` after the turn); the
+     * session path reads the same facts from the live session's own transcript (`getLeafId` before,
+     * `getBranch` after). Both read Pi's own entries rather than counting, because Pi writes entry types
+     * that are not messages (`model_change`, `thinking_level_change`, `compaction`, ...) and only Pi knows
+     * which line the user message is.
      *
      * Failing to produce one is NOT a turn failure - the answer has already streamed by then - so it is
      * never awaited on the critical path and never thrown. A message with no entry id simply cannot be a
      * revert boundary, which the revert handler reports in words.
      */
     onUserEntry?: (entryId: string) => void | Promise<void>;
-    /** Session file Pi resolved for the live worker. A host may cache it as a locator for a later revert. */
+    /**
+     * The session file Pi resolved for this conversation. A host caches it as a locator for a later revert
+     * or fork. The one-shot path learns it from `get_state`; the session path reads it off the live session
+     * and reports it when it CHANGES - a session rebuild (revert, eviction, fingerprint change) is exactly
+     * when the cached locator needs refreshing.
+     */
     onSessionFile?: (path: string) => void | Promise<void>;
     /**
      * Called once per `tool_execution_start`, with the tool's name and the bounded label naming what it was
@@ -276,6 +284,17 @@ export interface AgentRuntime {
      * directory themselves, so the picker and the spawn can never disagree about which definition is live.
      */
     agentFor?(conversation: Pick<Conversation, "id" | "agentId">): Promise<AgentDefinition | undefined>;
+    /**
+     * Throws away the live sessions this runtime holds.
+     *
+     * A runtime that keeps a session alive between turns has to be told, at shutdown, that those
+     * sessions should go: a stopped TURN is not a stopped SESSION, and a session nobody stops holds a
+     * model client and - on Windows - a lock on the conversation's working directory.
+     *
+     * Optional, because a runtime with no sessions behind it (the welcome runtime) has nothing to
+     * throw away.
+     */
+    disposeSessions?(conversationId?: string): Promise<void>;
     /**
      * The model/thinking catalog a picker lists. `selection` scopes the answer to one model's
      * capabilities, because Pi's thinking levels are per model (`getSupportedThinkingLevels`,
@@ -326,28 +345,6 @@ export declare class WelcomeRuntime implements AgentRuntime {
  * 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 declare function describePiQueue(record: RpcRecord): PiQueueSnapshot | undefined;
-/**
- * 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 declare function describeDeliveredUserMessage(record: RpcRecord): string | undefined;
 /** A line to write back to Pi's stdin. Mirrors Pi's RpcExtensionUIResponse union (rpc-types.ts:294-297). */
 export type ExtensionUiResponse = {
     type: "extension_ui_response";
@@ -450,6 +447,10 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * 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.
      */
     private readonly options;
     private memory?;
@@ -457,6 +458,43 @@ export declare class PiRpcRuntime implements AgentRuntime {
     private knowledge?;
     setKnowledge(knowledge: KnowledgeBase): void;
     private readonly runs;
+    /**
+     * 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.
+     */
+    private readonly 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.
+     */
+    private readonly activeTurns;
+    /**
+     * 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.
+     */
+    private readonly sessionHosts;
+    /** The sessions whose extension runner already has the UI bridge bound. */
+    private readonly uiBoundSessions;
+    /**
+     * 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.
+     */
+    private readonly reportedSessionFiles;
     /**
      * `steer` commands written to a child and not yet answered by Pi, keyed by the command id.
      *
@@ -475,6 +513,18 @@ export declare class PiRpcRuntime implements AgentRuntime {
     private readonly pendingCatalogs;
     /** Latches the "no extension on disk" warning, so it is said once rather than once per turn. */
     private warnedMissingExtension;
+    /** Latches the "Pi's SDK is not installed" warning, for the same reason. */
+    private warnedMissingSdk;
+    /**
+     * How a CONVERSATION runs: on a persistent SDK session, or by spawning a Pi for every turn.
+     *
+     *  is the slower one, and it exists for the test suite: those suites drive a fake Pi that
+     * speaks the RPC protocol over a pipe, and a program is not a library - the session path cannot run
+     * it. It is an explicit request rather than something inferred from which Pi happens to be named,
+     * because inferring it is what made the Pi extension start conversations on the slow path without
+     * saying why.
+     */
+    private readonly sessionMode;
     /**
      * 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
@@ -517,6 +567,10 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * 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?: {
         endpoint?: string;
@@ -526,7 +580,66 @@ export declare class PiRpcRuntime implements AgentRuntime {
         questionEndpoint?: string;
         toolsEndpoint?: string;
         uploadsDir?: string;
+        sessionFactory?: PiSessionFactory;
+        sessionMode?: "sdk" | "oneshot";
     });
+    /**
+     * 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.
+     */
+    private readonly builtSessions;
+    /** The configuration a conversation's session was built with, if one was built. */
+    builtSessionConfig(conversationId: string): {
+        tools?: string[];
+        excludeTools?: string[];
+        systemPromptFile?: string;
+        systemPromptMode?: "replace" | "append";
+        extensionPaths: string[];
+        extensionEnv: Record<string, string>;
+        model?: {
+            provider: string;
+            modelId: string;
+        };
+        thinkingLevel?: string;
+    } | undefined;
+    /**
+     * Which path a CONVERSATION on this runtime takes.
+     *
+     * Exposed so a test can assert it. The bug this exists to prevent was invisible from the outside:
+     * the version number said 0.1.95 while every conversation was still spawning a process per turn,
+     * and nothing said why. A test that can ask "would a conversation here spawn a Pi?" can catch that.
+     */
+    get conversationPath(): "sdk" | "oneshot";
+    /**
+     * 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.
+     */
+    sessionSupport(): Promise<{
+        available: true;
+    } | {
+        available: false;
+        reason: string;
+    }>;
+    /**
+     * 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.
+     */
+    disposeSessions(conversationId?: string): Promise<void>;
+    /** Throws away the sessions that have been idle for a while. */
+    evictIdleSessions(): Promise<void>;
     /**
      * The agent a conversation runs as, or undefined for Pi's own defaults.
      *
@@ -565,8 +678,120 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * 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.
+     */
     private taskExtensionEnv;
-    answer({ conversation, prompt, signal, cwd, host, onPiQueue, onSteerDelivered, onUserEntry, onSessionFile, onToolCall, onToolUpdate, onToolPreparing, onToolEnd, onThinking, onThinkingEnd, images, memoryReview, memorySourceConversationId, knowledgeRerank }: AnswerInput): AsyncIterable<string>;
+    /**
+     * 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.
+     */
+    private oneShotExtensionEnv;
+    /**
+     * 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.
+     */
+    sessionConfiguration(conversation: Conversation, cwd: string): Promise<{
+        tools?: string[];
+        excludeTools?: string[];
+        systemPromptFile?: string;
+        systemPromptMode?: "replace" | "append";
+        extensionPaths: string[];
+        extensionEnv: Record<string, string>;
+        model?: {
+            provider: string;
+            modelId: string;
+        };
+        thinkingLevel?: string;
+    }>;
+    private answerOnSession;
+    /**
+     * 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.
+     */
+    private extensionUiBridge;
+    /**
+     * 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".
+     */
+    private recordSessionTurnEntryId;
+    /**
+     * 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.
+     */
+    private extensionToolNames;
+    answer(input: AnswerInput): AsyncIterable<string>;
+    /**
+     * 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`.
+     */
+    private answerOneShot;
     /**
      * Reads back the id of the user message this turn just created, and hands it to the caller.
      *
@@ -703,6 +928,14 @@ export declare class PiRpcRuntime implements AgentRuntime {
         cwd: string;
         signal?: AbortSignal;
     }): Promise<string>;
+    /**
+     * 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.
+     */
+    private sessionFor;
     steer(conversationId: string, message: string, images?: MessageImage[]): Promise<SteerDisposition>;
     /**
      * The model/thinking catalog, from Pi, cached.