@evandu/super-pi 0.1.85 → 0.1.86

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-C_giUkvT.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-B3QVoYJY.css">
   </head>
   <body>
     <div id="root"></div>

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/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>;
+}

package/dist/server/tool-llm.js

@@ -0,0 +1,139 @@
+/**
+ * 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.
+ */
+/** 32KB of prompt is a paragraph of a book; more than that is a tool trying to move a transcript. */
+export const MAX_TOOL_LLM_PROMPT_BYTES = 32_000;
+/** 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 const MAX_TOOL_LLM_RESPONSE_BYTES = 64_000;
+export const MAX_TOOL_LLM_TIMEOUT_MS = 5 * 60_000;
+const DEFAULT_TOOL_LLM_TIMEOUT_MS = 60_000;
+/** A tool that fires a hundred calls in a loop gets refused, loudly, instead of quietly costing money. */
+const MAX_IN_FLIGHT_PER_TOOL = 3;
+const MAX_IN_FLIGHT_TOTAL = 8;
+export class ToolLlmService {
+    runtime;
+    cwd;
+    runs = new Map();
+    constructor(runtime, cwd) {
+        this.runtime = runtime;
+        this.cwd = cwd;
+    }
+    /** 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() { return typeof this.runtime?.askOnce === "function"; }
+    start(request) {
+        if (!this.available)
+            throw new Error("这台机器上没有可用的 Pi 运行时，工具无法调用模型。");
+        const prompt = typeof request.prompt === "string" ? request.prompt.trim() : "";
+        if (!prompt)
+            throw new Error("请提供要问模型的内容。");
+        if (Buffer.byteLength(prompt) > MAX_TOOL_LLM_PROMPT_BYTES)
+            throw new Error(`提问太长（上限 ${Math.round(MAX_TOOL_LLM_PROMPT_BYTES / 1024)}KB）。`);
+        const system = typeof request.system === "string" ? request.system.trim() : "";
+        if (system && Buffer.byteLength(system) > MAX_TOOL_LLM_PROMPT_BYTES)
+            throw new Error("系统提示太长。");
+        const running = [...this.runs.values()].filter((active) => active.run.status === "running");
+        if (running.length >= MAX_IN_FLIGHT_TOTAL)
+            throw new Error("已经有太多模型请求在排队，请稍后再试。");
+        if (running.filter((active) => active.run.toolId === request.toolId).length >= MAX_IN_FLIGHT_PER_TOOL)
+            throw new Error("这个工具同时在等的模型请求已经到上限了。");
+        const timeoutMs = Number.isFinite(request.timeoutMs) ? Math.max(1_000, Math.min(MAX_TOOL_LLM_TIMEOUT_MS, Math.floor(request.timeoutMs))) : DEFAULT_TOOL_LLM_TIMEOUT_MS;
+        const id = `toolllm_${randomId()}`;
+        const run = { id, toolId: request.toolId, status: "running", startedAt: new Date().toISOString(), text: "", promptChars: prompt.length };
+        const controller = new AbortController();
+        // The deadline is this service's own, not the frame's: a frame that stops polling does not get to keep
+        // a Pi process and a model call alive.
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        timer.unref();
+        const active = { run, controller, timer };
+        this.runs.set(id, active);
+        void (async () => {
+            try {
+                // Narrowed by `available` in `start`, and captured here: the service outlives any single call.
+                const ask = this.runtime?.askOnce?.bind(this.runtime);
+                if (!ask)
+                    throw new Error("这台机器上没有可用的 Pi 运行时，工具无法调用模型。");
+                const answer = await ask({
+                    prompt: system ? `${system}\n\n---\n\n${prompt}` : prompt,
+                    timeoutMs,
+                    cwd: this.cwd,
+                    signal: controller.signal,
+                });
+                if (active.run.status !== "running")
+                    return;
+                active.run.text = clip(answer);
+            }
+            catch (error) {
+                if (active.run.status !== "running")
+                    return;
+                const message = error instanceof Error ? error.message : String(error);
+                active.run.status = controller.signal.aborted && active.run.finishedAt === undefined ? "timed_out" : "failed";
+                active.run.error = controller.signal.aborted ? `模型在 ${Math.round(timeoutMs / 1000)} 秒内没有返回` : message;
+            }
+            finally {
+                clearTimeout(timer);
+                if (active.run.status === "running")
+                    active.run.status = "succeeded";
+                active.run.finishedAt ??= new Date().toISOString();
+                active.run.elapsedMs = Date.now() - Date.parse(active.run.startedAt);
+                // Bounded memory: a tool that made a thousand calls must not leave a thousand answers in the map.
+                if (this.runs.size > 64) {
+                    const oldest = [...this.runs.entries()].filter(([, entry]) => entry.run.status !== "running").sort((a, b) => Date.parse(a[1].run.finishedAt ?? "") - Date.parse(b[1].run.finishedAt ?? "")).slice(0, this.runs.size - 64);
+                    for (const [key] of oldest)
+                        this.runs.delete(key);
+                }
+            }
+        })();
+        return copy(run);
+    }
+    get(id, toolId) { const active = this.runs.get(id); return active?.run.toolId === toolId ? copy(active.run) : undefined; }
+    cancel(id, toolId) {
+        const active = this.runs.get(id);
+        if (!active || active.run.toolId !== toolId)
+            return undefined;
+        if (active.run.status === "running") {
+            active.controller.abort();
+            active.run.status = "cancelled";
+            active.run.error = "已取消";
+        }
+        return copy(active.run);
+    }
+    async wait(id, toolId, signal) {
+        const deadline = Date.now() + MAX_TOOL_LLM_TIMEOUT_MS + 5_000;
+        for (;;) {
+            const run = this.get(id, toolId);
+            if (!run)
+                throw new Error("这次模型请求不存在或已经过期。");
+            if (run.status !== "running")
+                return run;
+            if (signal?.aborted)
+                throw new Error("已取消");
+            if (Date.now() > deadline)
+                throw new Error("等待模型回答超时。");
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+    }
+}
+function clip(text) {
+    const buffer = Buffer.from(text, "utf8");
+    if (buffer.length <= MAX_TOOL_LLM_RESPONSE_BYTES)
+        return text;
+    return buffer.subarray(0, MAX_TOOL_LLM_RESPONSE_BYTES).toString("utf8");
+}
+function copy(run) { return { ...run }; }
+function randomId() { return globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2); }