@evandu/super-pi 0.1.85 → 0.1.87

package/dist/client/index.html

@@ -8,8 +8,8 @@
     <link rel="alternate icon" href="/favicon.ico" />
     <link rel="apple-touch-icon" href="/favicon.svg" />
     <title>Super Pi</title>
-    <script type="module" crossorigin src="/assets/index-B_jOwjyp.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CNNGl4eF.css">
+    <script type="module" crossorigin src="/assets/index-Dh3QFthH.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BfK8kaCv.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/server/application/run-service.js

@@ -838,24 +838,63 @@ export class RunService {
         // Written first, the message is in the transcript in the same frame, whether it starts a turn or
         // waits for one, and the guard below only decides WHICH. It also means the client-supplied `clientId`
         // is attached to a real message either way, so there is nothing to reconcile afterwards.
-        const message = await this.store.addUserMessage(conversationId, trimmed, validImages, attachments, { clientId, delivery: "waiting" });
+        //
+        // BUT "WHICH" IS DECIDED BEFORE THE WRITE, not at the guard, and that ordering is the fix for a bug
+        // the other order cannot fix: a message that is going to start a turn has no business passing through
+        // 「等待回答」 on its way there. Send into an idle conversation and the reader watches a queue badge
+        // light up, a row appear in the dock, and both disappear a frame later - a queue that was never one,
+        // for a turn that had already begun. The state a message is born into is a claim about it, and a claim
+        // retracted in the next frame is worse than never making it.
+        //
+        // Reading the slot here and claiming it below leaves a window between them, and the window is real:
+        // `message.send` runs outside the socket's command queue precisely so a follow-up can overtake a
+        // command already in flight, so two sends CAN be inside this method at the same time. The loser wrote
+        // itself as an ordinary message and now finds the slot taken - its words are on screen with nobody
+        // going to answer them. Repairing that is what the guard below is for; it is not a rare path, it is
+        // what two fast sends looks like from the inside.
+        const busy = this.activeRuns.has(conversation.id);
+        const message = await this.store.addUserMessage(conversationId, trimmed, validImages, attachments, { clientId, ...(busy ? { delivery: "waiting" } : {}) });
         this.broadcaster.broadcastState();
         // Claim the run slot synchronously (no await between has() and set()) so two
         // rapid sends can never both pass the guard and start concurrent turns.
-        if (this.activeRuns.has(conversation.id))
+        if (this.activeRuns.has(conversation.id)) {
+            if (!busy) {
+                // Lost the race described above. No turn has opened on this message and no model has seen it, so
+                // calling it waiting is a statement of fact - and it puts the words exactly where a message born
+                // waiting would have put them, which is the only place a person can find them.
+                await this.store.markMessageWaiting(conversationId, message.id);
+                this.broadcaster.broadcastState();
+            }
             return;
+        }
         const controller = new AbortController();
         this.activeRuns.set(conversation.id, controller);
         try {
-            if (validImages?.length) {
-                const catalog = await this.runtime.catalog(conversation.model);
-                const currentModel = catalog.models.find((model) => model.provider === conversation.model?.provider && model.modelId === conversation.model?.modelId)
-                    ?? catalog.models.find((m) => m.provider === catalog.defaultModel?.provider && m.modelId === catalog.defaultModel?.modelId);
-                if (currentModel && !currentModel.imageInput) {
-                    throw new Error(`当前选择的模型「${currentModel.label || currentModel.modelId}」不支持图片输入`);
+            let expanded;
+            try {
+                if (validImages?.length) {
+                    const catalog = await this.runtime.catalog(conversation.model);
+                    const currentModel = catalog.models.find((model) => model.provider === conversation.model?.provider && model.modelId === conversation.model?.modelId)
+                        ?? catalog.models.find((m) => m.provider === catalog.defaultModel?.provider && m.modelId === catalog.defaultModel?.modelId);
+                    if (currentModel && !currentModel.imageInput) {
+                        throw new Error(`当前选择的模型「${currentModel.label || currentModel.modelId}」不支持图片输入`);
+                    }
                 }
+                expanded = await expandAtReferences(this.store, workspace, trimmed);
+            }
+            catch (error) {
+                // EVERY REFUSAL ABOVE HAPPENS BEFORE A TURN EXISTS. The words are on screen and no model has seen
+                // them, so failing here must not leave a bubble that nothing will ever answer: they go back to
+                // the queue, where they can be seen, cancelled or sent again. On the queueing path this is the
+                // state they were born in and nothing changed; on the idle path it is the difference between
+                // 「消息发出去了但没有回答」 and a message the person can still act on.
+                //
+                // The boundary is the shape of the code, not a flag: `runConversationTurns` opens the turn on its
+                // first line, so it is outside this try for exactly that reason. A failure from in there is a turn
+                // that has already consumed these words, and putting them back would send them twice.
+                await this.store.markMessageWaiting(conversationId, message.id).catch(() => undefined);
+                throw error;
             }
-            const expanded = await expandAtReferences(this.store, workspace, trimmed);
             await this.runConversationTurns(conversation, workspace, expanded, controller, message.id, validImages);
             await this.store.setStatus(conversation.id, controller.signal.aborted ? "stopped" : "completed");
         }

package/dist/server/http-server.js

@@ -1,6 +1,6 @@
 import { createReadStream, existsSync } from "node:fs";
 import { spawn } from "node:child_process";
-import { readdir, stat } from "node:fs/promises";
+import { readdir, rm, stat } from "node:fs/promises";
 import { createServer } from "node:http";
 import { homedir, networkInterfaces } from "node:os";
 import { basename, dirname, extname, join, relative, resolve } from "node:path";
@@ -10,6 +10,7 @@ import { checkDiskVersion } from "./version.js";
 import { gitDiff, gitLog, gitStatus } from "./git.js";
 import { verifyCapability } from "./capability.js";
 import { MAX_KNOWLEDGE_REQUEST_BYTES } from "./knowledge.js";
+import { MAX_TOOL_BODY_BYTES } from "./tool-registry.js";
 import { packageUpdateArgs } from "./update.js";
 const MIME_TYPES = {
     ".css": "text/css; charset=utf-8",
@@ -50,6 +51,28 @@ function toolBrowserSdk() {
       }
     },
     runAndWait: async (params = {}, options) => { const run = await api.run(params); return api.wait(run.id, options); },
+    // THE MODEL, ASKED ON THE TOOL'S BEHALF. One call, one answer, no client to write: Super Pi owns the
+    // credentials, the model choice and the ceilings, and the tool only ever sees the text. It is a
+    // completion, not an agent - the model that answers has no tools, no files and no session history.
+    // Only a tool registered with permissions.llm may call it; otherwise the server refuses.
+    llm: (input = {}) => request("./api/llm", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(input) }),
+    llmGet: (callId) => request("./api/llm/" + encodeURIComponent(callId), { method: "GET" }),
+    llmCancel: (callId) => request("./api/llm/" + encodeURIComponent(callId), { method: "DELETE" }),
+    llmWait: async (callId, { intervalMs = 400, signal } = {}) => {
+      for (;;) {
+        if (signal && signal.aborted) throw new DOMException("Aborted", "AbortError");
+        const call = await api.llmGet(callId);
+        if (call.status !== "running") {
+          if (call.status !== "succeeded") throw new Error(call.error || "Super Pi's model call did not succeed");
+          return call;
+        }
+        await new Promise((resolve, reject) => {
+          const timer = setTimeout(resolve, Math.max(50, intervalMs));
+          if (signal) signal.addEventListener("abort", () => { clearTimeout(timer); reject(new DOMException("Aborted", "AbortError")); }, { once: true });
+        });
+      }
+    },
+    llmText: async (input = {}, options) => { const call = await api.llm(input); return (await api.llmWait(call.id, options)).text; },
   };
   Object.freeze(api);
   Object.defineProperty(window, "SuperPiTool", { value: api, writable: false, configurable: false });
@@ -206,10 +229,35 @@ export function createHttpServer(options) {
         const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
         const remote = request.socket.remoteAddress ?? "";
         const json = (status, body) => { response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" }); response.end(JSON.stringify(body)); };
+        if (url.pathname === "/api/tools/export") {
+            // NOT EXEMPT FROM THE TOKEN CHECK ABOVE, and that is deliberate: an export hands out a tool's
+            // whole source, so it is a management read exactly like GET and DELETE, not a capability call.
+            try {
+                const id = url.searchParams.get("id");
+                if (!id) {
+                    json(400, { error: "id required" });
+                    return;
+                }
+                const exported = await toolRegistry.exportBundle(id);
+                if (!exported) {
+                    json(404, { error: "tool not found" });
+                    return;
+                }
+                json(200, exported);
+                return;
+            }
+            catch (error) {
+                json(400, { error: error instanceof Error ? error.message : "tool export failed" });
+                return;
+            }
+        }
         if (url.pathname === "/api/tools") {
             try {
                 if (request.method === "GET") {
-                    json(200, { tools: await toolRegistry.list() });
+                    // The environment state is DERIVED per request and deliberately not stored: it changes when
+                    // the user installs Python, when a tool's venv is built, and when nothing at all happens.
+                    const tools = await toolRegistry.list();
+                    json(200, { tools: await Promise.all(tools.map(async (tool) => ({ ...tool, environmentState: await toolRunner.environmentState(tool) }))) });
                     return;
                 }
                 if (request.method === "DELETE") {
@@ -219,6 +267,11 @@ export function createHttpServer(options) {
                         return;
                     }
                     const removed = await toolRegistry.remove(id);
+                    // The venv is machine-local state that belongs to that tool and nothing else, so it goes with
+                    // it. Leaving it behind would mean a re-registered tool of the same slug silently inherits a
+                    // stale environment.
+                    if (removed)
+                        await rm(toolRunner.envDir(id), { recursive: true, force: true });
                     if (removed)
                         broadcaster.broadcast({ type: "tools.updated", tools: await toolRegistry.list() });
                     json(removed ? 200 : 404, { ok: removed });
@@ -228,13 +281,18 @@ export function createHttpServer(options) {
                     json(405, { error: "method" });
                     return;
                 }
-                let raw = "";
+                // BYTES, NOT CHARACTERS, AND FROM THE REGISTRY'S OWN CONSTANT. The old cap counted UTF-16 code
+                // units at 256,000, below the registry's own 512,000-byte asset limit, so JSON escaping decided
+                // where the real ceiling was and an exported bundle could be refused on the way back in.
+                let raw = "", bytes = 0;
                 for await (const chunk of request) {
-                    raw += chunk;
-                    if (raw.length > 256_000) {
+                    const piece = chunk;
+                    bytes += piece.length;
+                    if (bytes > MAX_TOOL_BODY_BYTES) {
                         json(413, { error: "request too large" });
                         return;
                     }
+                    raw += piece.toString("utf8");
                 }
                 const body = JSON.parse(raw);
                 if (!isAuthorized(request, accessToken)) {
@@ -252,7 +310,16 @@ export function createHttpServer(options) {
                     json(400, { error: "slug, name and files are required" });
                     return;
                 }
-                const tool = await toolRegistry.register({ slug: body.slug, name: body.name, description: body.description, entrypoint: body.entrypoint, script: body.script, files: body.files });
+                // AN IMPORTED BUNDLE KEEPS THE EXPORTER'S FINGERPRINT. It describes where the tool was written
+                // and verified, and overwriting it with the importer's own machine would erase the very
+                // difference the tool list exists to show. A tool with no fingerprint gets one measured here.
+                let environment = body.environment;
+                if (environment && !environment.fingerprint) {
+                    const local = await toolRunner.describeLocalPython();
+                    if (local)
+                        environment = { ...environment, fingerprint: { python: local.python, platform: local.platform, packages: environment.requires } };
+                }
+                const tool = await toolRegistry.register({ slug: body.slug, name: body.name, description: body.description, entrypoint: body.entrypoint, script: body.script, environment, permissions: body.permissions, files: body.files });
                 broadcaster.broadcast({ type: "tools.updated", tools: await toolRegistry.list() });
                 json(201, tool);
                 return;
@@ -316,7 +383,7 @@ export function createHttpServer(options) {
                         toolApi(404, { error: "python script is not registered" });
                         return;
                     }
-                    const run = toolRunner.start({ toolId: id, script: resolve(resolved.root, resolved.tool.script.path), cwd: resolved.root, definition: resolved.tool.script, params: body.params ?? {} });
+                    const run = toolRunner.start({ toolId: id, script: resolve(resolved.root, resolved.tool.script.path), cwd: resolved.root, definition: resolved.tool.script, params: body.params ?? {}, environment: resolved.tool.environment });
                     toolApi(202, run);
                 }
                 catch (error) {
@@ -363,6 +430,91 @@ export function createHttpServer(options) {
                 toolApi(405, { error: "method" });
                 return;
             }
+            // ---- THE MODEL, ON THE TOOL'S OWN BEHALF ---------------------------------------------------
+            // A tool asking the model a question, over the same relative API as its Python jobs, so the frame
+            // still never learns an id, a path or a credential. Three gates, in this order:
+            //   1. the opaque sandbox origin - identical to every other tool API here;
+            //   2. the tool must CARRY the grant (`permissions.llm`), which is the thing the review card showed
+            //      the person before they accepted the file. A tool that quietly started asking the model
+            //      would be spending the user's quota from inside a sandbox they were told was isolated;
+            //   3. the run is bound to this tool id, so one frame cannot read or cancel another's answer.
+            const llmStart = /^api\/llm$/.exec(resource);
+            const llmRun = /^api\/llm\/([^/]+)$/.exec(resource);
+            if (llmStart || llmRun) {
+                if (!toolOrigin) {
+                    toolApi(403, { error: "tool runtime API is only available to the sandboxed tool frame" });
+                    return;
+                }
+                // GRANT FIRST, THEN RUNTIME. What a tool is allowed to ask is a fact about the tool and does not
+                // depend on whether this machine happens to have a model, so a tool with no grant gets the same
+                // 403 whether or not Pi is installed.
+                if (!listed.permissions?.llm) {
+                    toolApi(403, { error: "这个工具没有调用模型的权限；注册或导入时它必须声明 permissions: { llm: true }。" });
+                    return;
+                }
+                if (!context.toolLlm?.available) {
+                    toolApi(503, { error: "这台机器上没有可用的 Pi 运行时，工具无法调用模型。" });
+                    return;
+                }
+                if (llmStart) {
+                    if (request.method === "OPTIONS") {
+                        response.writeHead(204, { "access-control-allow-origin": "null", "access-control-allow-methods": "POST", "access-control-allow-headers": "content-type", "access-control-max-age": "300", "vary": "Origin" }).end();
+                        return;
+                    }
+                    if (request.method !== "POST") {
+                        toolApi(405, { error: "method" });
+                        return;
+                    }
+                    let raw = "";
+                    for await (const chunk of request) {
+                        raw += chunk;
+                        if (raw.length > 64_000) {
+                            toolApi(413, { error: "request too large" });
+                            return;
+                        }
+                    }
+                    try {
+                        const body = JSON.parse(raw);
+                        toolApi(202, context.toolLlm.start({ toolId: id, prompt: body.prompt ?? "", system: body.system, timeoutMs: body.timeoutMs }));
+                    }
+                    catch (error) {
+                        toolApi(400, { error: error instanceof Error ? error.message : "model call failed" });
+                    }
+                    return;
+                }
+                if (request.method === "OPTIONS") {
+                    response.writeHead(204, { "access-control-allow-origin": "null", "access-control-allow-methods": "GET, DELETE", "access-control-allow-headers": "content-type", "access-control-max-age": "300", "vary": "Origin" }).end();
+                    return;
+                }
+                let llmId;
+                try {
+                    llmId = decodeURIComponent(llmRun[1]);
+                }
+                catch {
+                    toolApi(400, { error: "Malformed tool resource" });
+                    return;
+                }
+                if (request.method === "GET") {
+                    const run = context.toolLlm.get(llmId, id);
+                    if (!run) {
+                        toolApi(404, { error: "model call not found" });
+                        return;
+                    }
+                    toolApi(200, run);
+                    return;
+                }
+                if (request.method === "DELETE") {
+                    const run = context.toolLlm.cancel(llmId, id);
+                    if (!run) {
+                        toolApi(404, { error: "model call not found" });
+                        return;
+                    }
+                    toolApi(200, run);
+                    return;
+                }
+                toolApi(405, { error: "method" });
+                return;
+            }
             if (resource === "super-pi-tool.js") {
                 response.writeHead(200, { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-store" }).end(toolBrowserSdk());
                 return;

package/dist/server/index.js

@@ -26,6 +26,7 @@ import { WsBroadcaster, WsServer } from "./ws-server.js";
 import { initRunningVersion } from "./version.js";
 import { ToolRegistry } from "./tool-registry.js";
 import { ToolRunner } from "./tool-runner.js";
+import { ToolLlmService } from "./tool-llm.js";
 // ------------------------------------------------------------- Environment & paths
 const rootDir = resolve(import.meta.dirname, "../..");
 initRunningVersion(rootDir);
@@ -54,7 +55,9 @@ const toolsEndpoint = `http://${internalHost}:${port}/api/tools`;
 // ------------------------------------------------------------- Core singletons
 const store = await openStateStore(dataDir, process.env.SUPER_PI_PERSISTENCE ?? "sqlite");
 const toolRegistry = new ToolRegistry(dataDir);
-const toolRunner = new ToolRunner();
+// The data dir is what makes a per-tool virtual environment possible: it lives at
+// `<dataDir>/tool-envs/<toolId>`, beside the tools rather than inside one.
+const toolRunner = new ToolRunner(dataDir);
 const initialAgentDirs = resolveAgentDirectories({
     customDirs: store.snapshot().customAgentDirs,
     rootDir,
@@ -77,6 +80,9 @@ const memory = new ActiveMemory(join(dataDir, "memories"), store, runtime);
 process.env.SUPER_PI_MEMORY_ENDPOINT = `http://${internalHost}:${port}/api/memory/tool`;
 if (runtime instanceof PiRpcRuntime)
     runtime.setMemory(memory);
+// The model a mounted tool may ask. It IS Pi: `PiRpcRuntime.askOnce` spawns its own child with nothing
+// attached but Pi, and a runtime without one reports itself unavailable rather than faking an answer.
+const toolLlm = new ToolLlmService(runtime, rootDir);
 const knowledge = new KnowledgeBase(join(dataDir, "knowledge"), store, runtime, new VectorIndex(join(dataDir, "knowledge")));
 process.env.SUPER_PI_KNOWLEDGE_ENDPOINT = `http://${internalHost}:${port}/api/knowledge/tool`;
 if (runtime instanceof PiRpcRuntime)
@@ -169,6 +175,7 @@ const serverContext = {
     execService,
     toolRegistry,
     toolRunner,
+    toolLlm,
     terminalEnabled: () => terminalService.enabled,
     terminalDisabledReason: () => terminalDisabledReason(),
 };

package/dist/server/runtime.d.ts

@@ -245,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
@@ -669,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

@@ -1360,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

@@ -52,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.
      *

package/dist/server/store.d.ts

@@ -419,6 +419,25 @@ export declare class Store {
      * claim the same message.
      */
     claimWaitingMessage(conversationId: string, messageId: string): Promise<Message>;
+    /**
+     * Puts ONE message into `waiting` when it has no delivery state at all.
+     *
+     * `releaseWaitingMessage` above moves `sending` BACK to `waiting`, which is a claim being taken back.
+     * This is the other direction: a message that was written as an ordinary sent message and has to join
+     * the queue after the fact. There are exactly two reasons it happens, and both are consequences of the
+     * decision being made before the write rather than after it (see `enqueueAndRun`):
+     *
+     * 1. Two sends raced. The second one read "idle", wrote itself as an ordinary message, and only then
+     *    found the run slot taken. Its words are unanswered, so it is a waiting message after all.
+     * 2. The preflight that runs between the write and the turn refused (a model that cannot read images,
+     *    an @-mention that could not be expanded). Nothing reached a model, so the words are still owed an
+     *    answer and belong in the queue where the user can see them and send them again.
+     *
+     * Both are restorations of a state that was briefly wrong, never a way to re-queue a message Pi holds:
+     * a `sending` message is refused here, which keeps this from becoming a back door around the one-way
+     * door `claimWaitingMessage` puts up.
+     */
+    markMessageWaiting(conversationId: string, messageId: string): Promise<Message | undefined>;
     /**
      * Puts ONE `sending` message back to `waiting`, for the one case that proves Pi never took it.
      *

package/dist/server/store.js

@@ -1365,6 +1365,37 @@ export class Store {
         await this.persistMessages(conversation);
         return structuredClone(message);
     }
+    /**
+     * Puts ONE message into `waiting` when it has no delivery state at all.
+     *
+     * `releaseWaitingMessage` above moves `sending` BACK to `waiting`, which is a claim being taken back.
+     * This is the other direction: a message that was written as an ordinary sent message and has to join
+     * the queue after the fact. There are exactly two reasons it happens, and both are consequences of the
+     * decision being made before the write rather than after it (see `enqueueAndRun`):
+     *
+     * 1. Two sends raced. The second one read "idle", wrote itself as an ordinary message, and only then
+     *    found the run slot taken. Its words are unanswered, so it is a waiting message after all.
+     * 2. The preflight that runs between the write and the turn refused (a model that cannot read images,
+     *    an @-mention that could not be expanded). Nothing reached a model, so the words are still owed an
+     *    answer and belong in the queue where the user can see them and send them again.
+     *
+     * Both are restorations of a state that was briefly wrong, never a way to re-queue a message Pi holds:
+     * a `sending` message is refused here, which keeps this from becoming a back door around the one-way
+     * door `claimWaitingMessage` puts up.
+     */
+    async markMessageWaiting(conversationId, messageId) {
+        const conversation = this.requireConversation(conversationId);
+        const message = conversation.messages.find((item) => item.id === messageId);
+        if (!message || message.role !== "user")
+            return undefined;
+        if (message.delivery === "sending")
+            throw new Error("这条消息已经交给 Agent 了");
+        if (message.delivery === "waiting")
+            return structuredClone(message);
+        message.delivery = "waiting";
+        await this.persistMessages(conversation);
+        return structuredClone(message);
+    }
     /**
      * Puts ONE `sending` message back to `waiting`, for the one case that proves Pi never took it.
      *

package/dist/server/tool-llm.d.ts

@@ -0,0 +1,65 @@
+/**
+ * A MOUNTED TOOL ASKING THE MODEL A QUESTION - bookkeeping, ceilings and the consent gate's server half.
+ *
+ * WHY A TOOL GETS THIS AT ALL. A tool author who wants a model in their tool should not be writing a
+ * client: no API key to store, no provider endpoint, no retry, no streaming, no cost ceiling. Pi already
+ * holds the credentials and the model configuration, so Super Pi owns the call and the tool asks for it
+ * over the same relative API it already uses for its Python jobs.
+ *
+ * WHY IT IS A COMPLETION AND NOT AN AGENT. `askOnce` spawns Pi with `--no-extensions --no-skills
+ * --no-mcp --no-context-files --no-prompt-templates`, so the model answering a tool's prompt has no
+ * tools, no files and no history. A tool that could make the agent run things would be handing a
+ * sandboxed iframe the user's whole machine, and the iframe is exactly the thing that must not have it.
+ *
+ * WHY EVERY CEILING IS HERE AND NOT IN THE FRAME. The caller is an opaque sandbox on someone else's
+ * machine. Prompt size, answer size, duration, and how many calls may be in flight at once are all
+ * decided by this file, because "the tool asked nicely" is not a limit.
+ */
+/** The slice of the runtime this needs, declared structurally for the same reason `KnowledgeRuntime` is. */
+export type ToolLlmRuntime = {
+    /** OPTIONAL, exactly as it is on `AgentRuntime`: a runtime with no Pi behind it has none. */
+    askOnce?(input: {
+        prompt: string;
+        timeoutMs: number;
+        cwd: string;
+        signal?: AbortSignal;
+    }): Promise<string>;
+};
+export type ToolLlmStatus = "running" | "succeeded" | "failed" | "cancelled" | "timed_out";
+export type ToolLlmRun = {
+    id: string;
+    toolId: string;
+    status: ToolLlmStatus;
+    startedAt: string;
+    finishedAt?: string;
+    /** The model's answer. Bounded by MAX_TOOL_LLM_RESPONSE_BYTES, and this is the only copy. */
+    text: string;
+    promptChars: number;
+    elapsedMs?: number;
+    error?: string;
+};
+export type ToolLlmRequest = {
+    toolId: string;
+    prompt: string;
+    system?: string;
+    timeoutMs?: number;
+};
+/** 32KB of prompt is a paragraph of a book; more than that is a tool trying to move a transcript. */
+export declare const MAX_TOOL_LLM_PROMPT_BYTES = 32000;
+/** Answers are clipped rather than refused: a truncated answer is still an answer, and the model may be
+ *  mid-sentence when the ceiling lands. The clip is visible in `chars` being lower than expected. */
+export declare const MAX_TOOL_LLM_RESPONSE_BYTES = 64000;
+export declare const MAX_TOOL_LLM_TIMEOUT_MS: number;
+export declare class ToolLlmService {
+    private readonly runtime;
+    private readonly cwd;
+    private readonly runs;
+    constructor(runtime: ToolLlmRuntime | undefined, cwd: string);
+    /** WHY A MISSING RUNTIME IS A SENTENCE AND NOT A 500. The welcome runtime has no Pi behind it, and a
+     *  tool asking a question there should be told the machine cannot answer it. */
+    get available(): boolean;
+    start(request: ToolLlmRequest): ToolLlmRun;
+    get(id: string, toolId: string): ToolLlmRun | undefined;
+    cancel(id: string, toolId: string): ToolLlmRun | undefined;
+    wait(id: string, toolId: string, signal?: AbortSignal): Promise<ToolLlmRun>;
+}