@evandu/super-pi 0.1.84 → 0.1.86

package/dist/server/persistence/app-state-repository.d.ts

@@ -10,11 +10,35 @@ export type StateTransaction = {
     run: SubagentRun;
 } | {
     kind: "collections.replace";
-    values: Partial<Pick<AppState, "queuedMessages" | "workflows" | "backgroundTasks">>;
+    values: Partial<Pick<AppState, "workflows" | "backgroundTasks">>;
 } | {
     kind: "conversation.metadata";
     conversationId: string;
     metadata: Omit<AppState["conversations"][number], "messages">;
+}
+/**
+ * A rewrite of one conversation's whole message array, for the changes that are about the ARRAY rather
+ * than about one message's content: a waiting message being added, claimed, released, reordered,
+ * edited or withdrawn, and an assistant message being spliced in after the message it answers.
+ *
+ * It exists because of where the waiting list moved. Those used to be `collections.replace` writes
+ * against a `queuedMessages` array that sat outside every conversation, so they never touched the
+ * transcript - which is precisely why a steered message could be delivered to the model and leave no
+ * trace in the conversation the user was reading. A waiting message IS a message now, so the write is
+ * about messages, and it is still its own kind because the array is rewritten as a unit while
+ * `message.replace` deliberately never sees a list.
+ *
+ * `updatedAt` travels WITH the array because opening a turn changes it, and this is the only write that
+ * could record that. Leaving it out and clearing the timestamp overlay instead - the shape
+ * `conversation.metadata` uses, where the metadata is the payload - would make a reopened conversation
+ * report the timestamp of whatever the base snapshot happened to hold, which is a value the server
+ * already decided was wrong.
+ */
+ | {
+    kind: "conversation.messages";
+    conversationId: string;
+    messages: Message[];
+    updatedAt: string;
 };
 /** Durable backing store for the application's in-memory state snapshot. */
 export interface AppStateRepository {

package/dist/server/persistence/sqlite-state-repository.js

@@ -7,6 +7,19 @@ export class SqliteStateRepository {
         this.db.exec(`PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;
       CREATE TABLE IF NOT EXISTS state (id INTEGER PRIMARY KEY CHECK(id=1), json TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS messages (conversation TEXT NOT NULL, id TEXT NOT NULL, json TEXT NOT NULL, PRIMARY KEY(conversation,id));
+      /**
+       * Explicit transcript ORDER for a conversation, written by the conversation.messages transaction.
+       * Every other write path leaves message order in the base snapshot's array, which is fine as long as
+       * nothing ever REORDERS or REMOVES a message - and now something does: a waiting message can be
+       * moved within the group, or withdrawn, and both change which messages exist and in what sequence.
+       * Neither can be expressed by upserting a row per message id.
+       *
+       * It is AUTHORITATIVE once present, not a hint: load rebuilds that conversation's whole array from
+       * these rows rather than from the base json, because a withdrawn message is precisely one the base
+       * snapshot still contains and must NOT bring back. A conversation with no rows here is untouched and
+       * keeps reading its array from the snapshot, so this adds a code path rather than replacing one.
+       */
+      CREATE TABLE IF NOT EXISTS message_order (conversation TEXT NOT NULL, id TEXT NOT NULL, position INTEGER NOT NULL, json TEXT NOT NULL, PRIMARY KEY(conversation,id));
       CREATE TABLE IF NOT EXISTS timestamps (conversation TEXT PRIMARY KEY, stamp TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS collections (name TEXT PRIMARY KEY, json TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS metadata (conversation TEXT PRIMARY KEY, json TEXT NOT NULL);
@@ -35,9 +48,18 @@ export class SqliteStateRepository {
                 const message = JSON.parse(String(r.json));
                 return [message.id, message];
             }));
-            if (!Array.isArray(conversation.messages))
-                conversation.messages = [];
-            conversation.messages = conversation.messages.map(message => overrides.get(message.id) ?? message);
+            // An authoritative order row set means this conversation's transcript is rebuilt from it, rather
+            // than from the base snapshot's array. That is what makes a WITHDRAWN message stay withdrawn: the
+            // snapshot still lists it, and reading the array back would resurrect words the user took back.
+            const ordered = this.db.prepare("SELECT id,position,json FROM message_order WHERE conversation=? ORDER BY position").all(conversation.id);
+            if (ordered.length) {
+                conversation.messages = ordered.map(row => JSON.parse(String(row.json)));
+            }
+            else {
+                if (!Array.isArray(conversation.messages))
+                    conversation.messages = [];
+                conversation.messages = conversation.messages.map(message => overrides.get(message.id) ?? message);
+            }
             // Timestamp overlays are stored beside the base conversation metadata.
             const stamp = this.db.prepare("SELECT stamp FROM timestamps WHERE conversation=?").get(conversation.id);
             if (stamp?.stamp)
@@ -71,7 +93,7 @@ export class SqliteStateRepository {
     async save(state) {
         this.atomic(() => {
             this.db.prepare("INSERT INTO state VALUES(1,?) ON CONFLICT(id) DO UPDATE SET json=excluded.json").run(JSON.stringify(state));
-            this.db.exec("DELETE FROM messages; DELETE FROM runs; DELETE FROM timestamps; DELETE FROM collections; DELETE FROM metadata;");
+            this.db.exec("DELETE FROM messages; DELETE FROM message_order; DELETE FROM runs; DELETE FROM timestamps; DELETE FROM collections; DELETE FROM metadata;");
         });
     }
     async commit(transaction) {
@@ -91,6 +113,27 @@ export class SqliteStateRepository {
                 for (const [name, value] of Object.entries(transaction.values))
                     write.run(name, JSON.stringify(value));
             }
+            else if (transaction.kind === "conversation.messages") {
+                // Rewrite the WHOLE array, order included. A per-id upsert cannot express this transaction: it
+                // both reorders (a waiting message moving within its group) and removes (a withdrawn one), and
+                // both change which messages exist. Replacing the set is the honest write, and it is one
+                // transaction because a reader that saw the order without the content, or the content without
+                // the order, would see a transcript that was never true.
+                this.db.prepare("DELETE FROM message_order WHERE conversation=?").run(transaction.conversationId);
+                this.db.prepare("DELETE FROM messages WHERE conversation=?").run(transaction.conversationId);
+                const upsertMessage = this.db.prepare("INSERT INTO messages VALUES(?,?,?) ON CONFLICT(conversation,id) DO UPDATE SET json=excluded.json");
+                const insertOrdered = this.db.prepare("INSERT INTO message_order VALUES(?,?,?,?)");
+                transaction.messages.forEach((message, position) => {
+                    const json = JSON.stringify(message);
+                    upsertMessage.run(transaction.conversationId, message.id, json);
+                    insertOrdered.run(transaction.conversationId, message.id, position, json);
+                });
+                // The stamp is WRITTEN, not cleared. Opening a turn moves `updatedAt`, and this is the only write
+                // that can record it; clearing the overlay instead would leave the reopened conversation reporting
+                // whatever the base snapshot held, which is the value the server had already decided was wrong.
+                this.db.prepare("INSERT INTO timestamps VALUES(?,?) ON CONFLICT(conversation) DO UPDATE SET stamp=excluded.stamp")
+                    .run(transaction.conversationId, transaction.updatedAt);
+            }
             else {
                 this.db.prepare("INSERT INTO metadata VALUES(?,?) ON CONFLICT(conversation) DO UPDATE SET json=excluded.json")
                     .run(transaction.conversationId, JSON.stringify(transaction.metadata));

package/dist/server/runtime.d.ts

@@ -1,6 +1,7 @@
 import { type RpcRecord } from "./rpc-channel.js";
 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";
 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";
 /**
@@ -20,6 +21,16 @@ export interface AnswerInput {
     /** Internal isolated review: no built-in tools, delegation or user-session writes. */
     memoryReview?: boolean;
     memorySourceConversationId?: string;
+    /**
+     * Internal isolated one-shot: the knowledge reranker asking the model to order candidate passages.
+     *
+     * WHY IT IS A SEPARATE FLAG AND NOT A REUSE OF `memoryReview`. The two differ in what they must NOT
+     * have. A review legitimately needs the memory tools to write down what it finds; a reranker must
+     * have no tool surface at all - it only has to emit a JSON array, and any tool it reaches for is a
+     * wasted round trip inside somebody else's turn. Folding one into the other would hand the reranker
+     * the memory surface, which is exactly the wrong privilege for a read-only ranking task.
+     */
+    knowledgeRerank?: boolean;
     conversation: Conversation;
     prompt: string;
     images?: MessageImage[];
@@ -44,6 +55,27 @@ export interface AnswerInput {
      * unhandled and dropped is now read.
      */
     onPiQueue?(queue: PiQueueSnapshot): void;
+    /**
+     * Called when Pi STARTS A NEW USER MESSAGE of its own, mid-turn, carrying the text it is answering.
+     *
+     * This is the delivered-steer signal, and it is what makes a steered message visible in the
+     * transcript. Pi drains its steering queue at a turn boundary (`agent-loop.ts:295`) and announces the
+     * delivery by emitting `message_start` with the user message it just picked up
+     * (`agent-session.ts:1116-1136`) - so the boundary where a steer stops waiting and starts being
+     * answered is an EVENT, not something to infer.
+     *
+     * It used to be inferred, from a drop in `steering.length` on the `queue_update` above, and applied
+     * by deleting the oldest `sending` row. Two consequences, both bad: the message the user could no
+     * longer find in the queue was never written into the transcript at all, so the agent answered words
+     * that existed only in Pi's session file; and a count cannot say WHICH row, so an out-of-order
+     * snapshot could drop a row that had not been delivered. The text is passed so a host MAY match on
+     * it, but the honest primary key remains the oldest `sending` message, for the same reason Pi
+     * itself dequeues by `indexOf` on text and cannot tell two identical messages apart.
+     *
+     * Only fires for a steer this turn delivered, never for the prompt that started the turn: the prompt
+     * is not re-announced, and a caller's own state decides whether there was anything waiting at all.
+     */
+    onSteerDelivered?(text: string): void;
     /**
      * Called ONCE per turn with the Pi entry id of the user message that started it, or never.
      *
@@ -213,6 +245,30 @@ export interface AgentRuntime {
      * Absent on the welcome runtime, which has no Pi behind it.
      */
     summarizeConversation?(conversation: Conversation, cwd: string, signal?: AbortSignal): Promise<string>;
+    /**
+     * ONE-SHOT COMPLETION, FOR A MOUNTED TOOL. A throwaway Pi child, one prompt, one answer, then gone.
+     *
+     * WHY IT IS A SEPARATE CHILD, LIKE `summarizeConversation`: a turn's child is the one reading the
+     * user's stream. Writing a tool's prompt at it would land in the conversation the user is watching.
+     *
+     * WHY NOTHING IS ATTACHED BUT Pi ITSELF. `--no-extensions --no-skills --no-mcp --no-context-files
+     * --no-prompt-templates`, the same line the knowledge reranker uses: a tool asking the model a question
+     * must not be able to reach the user's files, the task tools, or a session history. A model that
+     * spends the turn on a tool call anyway gets no answer and the call times out - the same accepted
+     * failure mode the reranker documents.
+     *
+     * WHY IT CHOOSES NO MODEL. Pi's own default is the user's own default, and a sandboxed frame is the
+     * last place that should get to pick which model spends the user's quota.
+     *
+     * Absent on a runtime with no Pi behind it, which the caller reports as a refusal rather than
+     * pretending a model answered.
+     */
+    askOnce?(input: {
+        prompt: string;
+        timeoutMs: number;
+        cwd: string;
+        signal?: AbortSignal;
+    }): Promise<string>;
     /**
      * The agent a conversation runs as, read fresh from the agent directory. Absent on a runtime with
      * no agents (the welcome runtime), where every conversation runs as Pi itself. Callers that need an
@@ -279,6 +335,19 @@ export declare class WelcomeRuntime implements AgentRuntime {
  * 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";
@@ -385,6 +454,8 @@ export declare class PiRpcRuntime implements AgentRuntime {
     private readonly options;
     private memory?;
     setMemory(memory: ActiveMemory): void;
+    private knowledge?;
+    setKnowledge(knowledge: KnowledgeBase): void;
     private readonly runs;
     /**
      * `steer` commands written to a child and not yet answered by Pi, keyed by the command id.
@@ -495,7 +566,7 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * own address, so it is the same string on every turn and is read once from the constructor's options.
      */
     private taskExtensionEnv;
-    answer({ conversation, prompt, signal, cwd, host, onPiQueue, onUserEntry, onSessionFile, onToolCall, onToolUpdate, onToolPreparing, onToolEnd, onThinking, onThinkingEnd, images, memoryReview, memorySourceConversationId }: AnswerInput): AsyncIterable<string>;
+    answer({ conversation, prompt, signal, cwd, host, onPiQueue, onSteerDelivered, onUserEntry, onSessionFile, onToolCall, onToolUpdate, onToolPreparing, onToolEnd, onThinking, onThinkingEnd, images, memoryReview, memorySourceConversationId, knowledgeRerank }: AnswerInput): AsyncIterable<string>;
     /**
      * Reads back the id of the user message this turn just created, and hands it to the caller.
      *
@@ -622,6 +693,16 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * model; in the second the outcome is genuinely unknown and a `sending` state says so.
      */
     summarizeConversation(conversation: Conversation, cwd: string, signal?: AbortSignal): Promise<string>;
+    /**
+     * A single completion for a mounted tool. See `AgentRuntime.askOnce` for why it is its own child,
+     * why nothing is attached but Pi, and why it picks no model.
+     */
+    askOnce(input: {
+        prompt: string;
+        timeoutMs: number;
+        cwd: string;
+        signal?: AbortSignal;
+    }): Promise<string>;
     steer(conversationId: string, message: string, images?: MessageImage[]): Promise<SteerDisposition>;
     /**
      * The model/thinking catalog, from Pi, cached.

package/dist/server/runtime.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { RpcChannel } from "./rpc-channel.js";
 export { RpcChannel } from "./rpc-channel.js";
 import { randomUUID } from "node:crypto";
+import { KNOWLEDGE_TOOL_NAME } from "./knowledge.js";
 import { existsSync } from "node:fs";
 import { mkdir, stat } from "node:fs/promises";
 import { forkSessionFile, truncateSessionFile } from "./session-repository.js";
@@ -64,6 +65,32 @@ export function describePiQueue(record) {
         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);
@@ -257,6 +284,8 @@ export class PiRpcRuntime {
     options;
     memory;
     setMemory(memory) { this.memory = memory; }
+    knowledge;
+    setKnowledge(knowledge) { this.knowledge = knowledge; }
     runs = new Map();
     /**
      * `steer` commands written to a child and not yet answered by Pi, keyed by the command id.
@@ -411,7 +440,7 @@ export class PiRpcRuntime {
             [TASK_CAPABILITY_ENV]: capability,
         };
     }
-    async *answer({ conversation, prompt, signal, cwd, host, onPiQueue, onUserEntry, onSessionFile, onToolCall, onToolUpdate, onToolPreparing, onToolEnd, onThinking, onThinkingEnd, images, memoryReview, memorySourceConversationId }) {
+    async *answer({ 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 });
@@ -426,7 +455,7 @@ export class PiRpcRuntime {
         // them: its RPC command union (rpc-types.ts:20-74) has no prompt and no tools command, so there is
         // nothing to send after the process is already running. Fetched before the spawn so a definition
         // error fails the turn loudly instead of starting a Pi that silently ignores it.
-        const agent = memoryReview ? undefined : await this.agentFor(conversation);
+        const agent = memoryReview || knowledgeRerank ? undefined : await this.agentFor(conversation);
         const validationId = memorySourceConversationId ?? conversation.id;
         if (agent?.model)
             await this.modelValidator?.(validationId, { ...agent.model, label: agent.model.modelId });
@@ -443,24 +472,42 @@ export class PiRpcRuntime {
         // declared - broken with no error. An agent that says `task: false` still wins: `toolFlags` treats an
         // explicit false as outranking a host extra, which is what makes "this agent does not delegate" true
         // rather than advisory.
-        const extensionArgs = memoryReview ? [] : await this.taskExtensionArgs();
-        const memoryEnabled = this.memory ? (await this.memory.configuration()).enabled : false;
+        const extensionArgs = memoryReview || knowledgeRerank ? [] : await this.taskExtensionArgs();
+        // A reranker gets no memory capability at all. `memoryReview` mints one deliberately, because a
+        // review is supposed to write memory; a reranker must not be able to, so the token is simply
+        // never issued rather than issued with a flag.
+        const memoryEnabled = !knowledgeRerank && this.memory ? (await this.memory.configuration()).enabled : false;
         const memoryToken = memoryEnabled ? this.memory.issue(validationId, { review: memoryReview }) : undefined;
         const memoryExtension = resolve(import.meta.dirname, "../../agents/super-pi-memory/index.ts");
         const memoryArgs = memoryEnabled ? ["--extension", memoryExtension] : [];
+        // Mounted only when the workspace actually HAS documents. An empty knowledge base would otherwise
+        // cost a catalogue round trip and one declared tool on every turn to tell the model there is
+        // nothing to find. Review turns never mount it: a background reflection has no business
+        // retrieving documents it was not asked about, and its `--tools` line is a closed list. A
+        // reranker never mounts it either - it must not be able to call the search it is ranking.
+        const knowledgeEnabled = !memoryReview && !knowledgeRerank && !!this.knowledge && await this.knowledge.hasDocuments(conversation.workspaceId).catch(() => false);
+        const knowledgeToken = knowledgeEnabled ? this.knowledge.issue(conversation.id) : undefined;
+        const knowledgeExtension = resolve(import.meta.dirname, "../../agents/super-pi-knowledge/index.ts");
+        const knowledgeArgs = knowledgeEnabled ? ["--extension", knowledgeExtension] : [];
         // BOTH extension tools, or neither. Naming one while the other goes unmentioned would be a lie in a
         // different direction: Pi filters its registry through `--tools`, so an agent that declares
         // `tools: {"*": false, read: true}` gets whichever of the two is on this line and silently not the
         // other. They also share the extension's existence - `extensionArgs` is non-empty exactly when
         // `index.ts` is on disk and an endpoint was configured - so there is no case where one is mounted and
         // the other is not.
-        const agentArgs = memoryReview ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates", "--tools", "memory,skill_manage,session_search"] : await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: [...(extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, "question", "tool_register"] : []), ...(memoryEnabled ? ["memory", "skill_manage", "session_search"] : [])] });
+        // A RERANK SPAWNS WITH NOTHING ATTACHED BUT Pi ITSELF. No extensions, no skills, no MCP, no agent
+        // definition, no session-scoped tools - it has one job, which is to turn a list of passages into a
+        // list of indices. Note that Pi's BUILT-IN tools are not removed here: `--tools` needs a real
+        // allowlist and naming a tool Pi has not registered would change the spawn line for every other
+        // mode. The prompt asks for a bare JSON array and nothing else; if the model spends a turn on a
+        // tool call anyway the reranker times out and falls back to the lexical order.
+        const agentArgs = memoryReview ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates", "--tools", "memory,skill_manage,session_search"] : knowledgeRerank ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates"] : await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: [...(extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, "question", "tool_register"] : []), ...(memoryEnabled ? ["memory", "skill_manage", "session_search"] : []), ...(knowledgeEnabled ? [KNOWLEDGE_TOOL_NAME] : [])] });
         // Refused here, with the reason, rather than handed to the spawn: an ENOENT from `spawn` reads as
         // "the app is broken" and hides the one fact that matters, which is where it looked for Pi.
         if (!this.pi.found)
             throw new Error(this.pi.reason);
         // npm exposes global CLIs as .cmd shims on Windows; Node requires a shell to launch those shims.
-        const child = spawn(shellQuote(this.pi.command), ["--mode", "rpc", "--session-dir", this.sessionDir, "--session-id", conversation.id, ...extensionArgs, ...memoryArgs, ...agentArgs], {
+        const child = spawn(shellQuote(this.pi.command), ["--mode", "rpc", "--session-dir", this.sessionDir, "--session-id", conversation.id, ...extensionArgs, ...memoryArgs, ...knowledgeArgs, ...agentArgs], {
             cwd: childCwd,
             stdio: ["pipe", "pipe", "pipe"],
             shell: process.platform === "win32",
@@ -468,10 +515,13 @@ 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) ? { env: { ...process.env, ...(extensionArgs.length ? await this.taskExtensionEnv(conversation.id) : {}), ...(memoryEnabled ? {
+            ...((extensionArgs.length || memoryEnabled || knowledgeEnabled) ? { env: { ...process.env, ...(extensionArgs.length ? await this.taskExtensionEnv(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",
+                    } : {}), ...(knowledgeEnabled ? {
+                        SUPER_PI_KNOWLEDGE_ENDPOINT: process.env.SUPER_PI_KNOWLEDGE_ENDPOINT,
+                        SUPER_PI_KNOWLEDGE_TOKEN: knowledgeToken,
                     } : {}) } } : {}),
         });
         const channel = new RpcChannel(child);
@@ -616,6 +666,30 @@ export class PiRpcRuntime {
                         }
                         continue;
                     }
+                    // A STEER THIS TURN DELIVERED. Pi announces the moment it stops waiting and starts being
+                    // answered by emitting `message_start` with the user message it picked up
+                    // (`agent-session.ts:1116-1136`) - on the same stdout stream, immediately after the
+                    // `queue_update` above that shows the entry gone.
+                    //
+                    // READ, not dropped, and this is the fix rather than a nicety. It used to fall through to
+                    // `noteUnhandled`, which is why a steered message reached the model and never reached the
+                    // transcript: nothing here told the host that a new user message had begun, so the answer to
+                    // it was appended to the assistant message that was already streaming and the user's own words
+                    // were never written anywhere they could be read. A host can now split the turn at this
+                    // boundary and put the answer under the message it answers.
+                    //
+                    // It is consumed silently and NOT announced as unhandled, because `message_start` for a user
+                    // role is a delivery notice, not something a reader needs to be told about in a log.
+                    const steeredText = describeDeliveredUserMessage(record);
+                    if (steeredText !== undefined) {
+                        try {
+                            onSteerDelivered?.(steeredText);
+                        }
+                        catch (error) {
+                            console.warn(`PiRpcRuntime: the steer delivery handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
+                        }
+                        continue;
+                    }
                     // THE PRIMARY AGENT'S TOOL CALLS. Consumed, not announced - the same routing the sub-agent
                     // supervisor already does for its child (subagents.ts:532-559), on the same two records.
                     //
@@ -824,6 +898,8 @@ export class PiRpcRuntime {
             releaseCapability(conversation.id);
             if (memoryToken)
                 this.memory?.release(memoryToken);
+            if (knowledgeToken)
+                this.knowledge?.release(knowledgeToken);
             // A steer still unanswered when the turn ends is REJECTED, not left pending. The drain loop above
             // is the only reader of this child's stdout and it has stopped, so nothing would ever settle that
             // promise: the caller would wait for a timeout to learn something this process already knows. The
@@ -1284,6 +1360,51 @@ export class PiRpcRuntime {
                 await killTree(child.pid);
         }
     }
+    /**
+     * A single completion for a mounted tool. See `AgentRuntime.askOnce` for why it is its own child,
+     * why nothing is attached but Pi, and why it picks no model.
+     */
+    async askOnce(input) {
+        if (!this.pi.found)
+            throw new Error(this.pi.reason);
+        // A throwaway session id, for the same reason the autotitle child gets one: this exchange is not
+        // part of any conversation's transcript and must never be filed under one.
+        const child = spawn(shellQuote(this.pi.command), ["--mode", "rpc", "--session-dir", this.sessionDir, "--session-id", `tool-llm-${randomUUID()}`, "--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates"], {
+            cwd: resolve(input.cwd),
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: process.platform === "win32",
+        });
+        const channel = new RpcChannel(child);
+        const deadline = Date.now() + input.timeoutMs;
+        try {
+            channel.write({ id: "tool_llm", type: "prompt", message: input.prompt });
+            let settled = false, text = "";
+            while (!settled && Date.now() < deadline) {
+                if (input.signal?.aborted)
+                    throw new Error("已取消");
+                const record = await channel.next(100);
+                if (!record)
+                    continue;
+                if (record.type === "message_update" && record.assistantMessageEvent?.type === "text_delta")
+                    text += record.assistantMessageEvent.delta ?? "";
+                if (record.type === "agent_settled")
+                    settled = true;
+                if (record.type === "response" && record.id === "tool_llm" && record.success === false)
+                    throw new Error(record.error ?? "Pi 拒绝了这次请求");
+                if (child.exitCode !== null)
+                    throw new Error("模型进程意外退出");
+            }
+            if (!settled)
+                throw new Error(`模型在 ${Math.round(input.timeoutMs / 1000)} 秒内没有返回`);
+            if (!text.trim())
+                throw new Error("模型没有返回任何内容");
+            return text;
+        }
+        finally {
+            if (child.exitCode === null && child.pid !== undefined)
+                await killTree(child.pid);
+        }
+    }
     async steer(conversationId, message, images) {
         const run = this.runs.get(conversationId);
         if (!run || !this.canSteer(conversationId))

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

@@ -37,6 +37,7 @@ export interface EventBroadcaster {
  */
 export interface ServerContext {
     memory?: import("./active-memory.js").ActiveMemory;
+    knowledge?: import("./knowledge.js").KnowledgeBase;
     paths: ServerPaths;
     store: Store;
     runtime: AgentRuntime;
@@ -51,6 +52,8 @@ export interface ServerContext {
     execService: ExecService;
     toolRegistry: ToolRegistry;
     toolRunner: ToolRunner;
+    /** Absent only if construction failed; a runtime with no Pi reports itself through `available`. */
+    toolLlm?: import("./tool-llm.js").ToolLlmService;
     /**
      * Whether the right rail's terminal tab should exist, and why not when it should not.
      *