@evandu/super-pi 0.1.85 → 0.1.87

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); }

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

@@ -3,6 +3,36 @@ export type ToolAsset = {
     path: string;
     content: string;
 };
+/**
+ * WHAT A TOOL SAYS ABOUT THE PYTHON IT NEEDS, PLUS WHAT THE MACHINE THAT REGISTERED IT ACTUALLY HAD.
+ *
+ * `requires` is ALWAYS `pkg==version` and that is the whole point: an isolated venv decides WHERE the
+ * packages live, and the pin decides WHICH packages are there. Only the pin makes two machines agree,
+ * so a range is refused by name at import rather than warned about.
+ */
+export type ToolEnvironment = {
+    /** PEP 440 range such as ">=3.10,<4". Omitted means any Python this machine can resolve. */
+    requiresPython?: string;
+    requires?: string[];
+    /** MEASURED where the tool was registered, never guessed. Travels in the export bundle. */
+    fingerprint?: ToolFingerprint;
+};
+export type ToolFingerprint = {
+    python?: string;
+    platform?: string;
+    packages?: string[];
+};
+/**
+ * WHAT A TOOL IS ALLOWED TO ASK OF THE MACHINE IT RUNS ON.
+ *
+ * `llm` is a GRANT, not a hint: `POST /tools/<id>/api/llm` refuses a tool that does not carry it, so
+ * "this tool can spend your model quota" is something a person was shown before they accepted the file
+ * and stays true afterwards. A tool that needs a model has to say so - which is also what keeps the
+ * review card honest, because the warning is read off the record rather than guessed from the files.
+ */
+export type ToolPermissions = {
+    llm?: boolean;
+};
 export type MountedTool = {
     id: string;
     slug: string;
@@ -10,11 +40,27 @@ export type MountedTool = {
     description?: string;
     entrypoint: string;
     script?: ToolScript;
+    environment?: ToolEnvironment;
+    permissions?: ToolPermissions;
     source: "user" | "builtin";
     enabled: boolean;
     createdAt: string;
     updatedAt: string;
 };
+export declare const MAX_ASSETS = 32;
+export declare const MAX_ASSET_BYTES = 512000;
+/**
+ * THE HTTP BODY CAP, AND WHY IT IS DECLARED HERE RATHER THAN IN THE ROUTE.
+ *
+ * JSON escaping inflates the payload - every quote and every newline in a tool's HTML becomes two
+ * characters - so a body cap that merely matched MAX_ASSET_BYTES would refuse tools the registry
+ * itself would have accepted, and the real ceiling would depend on how much HTML a tool happened to
+ * contain. Doubling plus a fixed overhead leaves that inflation room, and keeping the number beside
+ * MAX_ASSET_BYTES keeps ONE number authoritative instead of two that disagree silently.
+ */
+export declare const MAX_TOOL_BODY_BYTES: number;
+export declare const EXPORT_FORMAT = "super-pi.tool";
+export declare const EXPORT_VERSION = 1;
 /** Global registry: a tool belongs to Super Pi, never to the workspace that created it. */
 export declare class ToolRegistry {
     private readonly file;
@@ -31,6 +77,8 @@ export declare class ToolRegistry {
         description?: string;
         entrypoint?: string;
         script?: ToolScript;
+        environment?: ToolEnvironment;
+        permissions?: ToolPermissions;
         files: ToolAsset[];
     }): Promise<MountedTool>;
     remove(id: string): Promise<boolean>;
@@ -39,4 +87,21 @@ export declare class ToolRegistry {
         file: string;
         root: string;
     } | undefined>;
+    /**
+     * THE EXPORT, AND THE ONLY PRODUCER OF A SHAREABLE BUNDLE.
+     *
+     * The client cannot assemble one (it never receives file content), and there is no CLI, script, or
+     * agent path on purpose: handing out a tool's source is something a person clicks.
+     *
+     * The bundle is FLAT, so the exported file is itself a valid `tool_register` payload - the same
+     * shape `POST /api/tools` takes. Nothing machine-local travels: no id (a fresh one is minted on
+     * import), no timestamps, and no way to reach Super Pi. A tool addresses its own runtime RELATIVELY
+     * (`./api/run`), the server derives which tool that is from the mount URL, and `SUPER_PI_TOOL_ID`
+     * is handed to Python at run time - so there is no binding inside the files that an import would
+     * have to rewrite, and nothing to leak when the file travels.
+     */
+    exportBundle(id: string): Promise<{
+        bundle: Record<string, unknown>;
+        skipped: string[];
+    } | undefined>;
 }

package/dist/server/tool-registry.js

@@ -1,6 +1,21 @@
-import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
-const MAX_TOOLS = 128, MAX_ASSETS = 32, MAX_ASSET_BYTES = 512_000, SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const MAX_ASSETS = 32;
+export const MAX_ASSET_BYTES = 512_000;
+/**
+ * THE HTTP BODY CAP, AND WHY IT IS DECLARED HERE RATHER THAN IN THE ROUTE.
+ *
+ * JSON escaping inflates the payload - every quote and every newline in a tool's HTML becomes two
+ * characters - so a body cap that merely matched MAX_ASSET_BYTES would refuse tools the registry
+ * itself would have accepted, and the real ceiling would depend on how much HTML a tool happened to
+ * contain. Doubling plus a fixed overhead leaves that inflation room, and keeping the number beside
+ * MAX_ASSET_BYTES keeps ONE number authoritative instead of two that disagree silently.
+ */
+export const MAX_TOOL_BODY_BYTES = MAX_ASSET_BYTES * 2 + 64_000;
+export const EXPORT_FORMAT = "super-pi.tool";
+export const EXPORT_VERSION = 1;
+const MAX_TOOLS = 128, SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const PINNED_REQUIREMENT = /^[A-Za-z0-9][A-Za-z0-9_.-]*==[^=\s,;<>|'"`\\]{1,80}$/;
 /** Global registry: a tool belongs to Super Pi, never to the workspace that created it. */
 export class ToolRegistry {
     file;
@@ -38,7 +53,10 @@ export class ToolRegistry {
         const files = normalizeAssets(input.files);
         if (!files.some((file) => file.path === entrypoint))
             throw new Error("entrypoint must be included in files");
-        const script = input.script ? normalizeScript(input.script, files) : undefined, finalDir = join(this.toolsDir, slug), stagingDir = `${finalDir}.${crypto.randomUUID()}.staging`;
+        const script = input.script ? normalizeScript(input.script, files) : undefined;
+        const environment = input.environment ? normalizeEnvironment(input.environment) : undefined;
+        const permissions = normalizePermissions(input.permissions);
+        const finalDir = join(this.toolsDir, slug), stagingDir = `${finalDir}.${crypto.randomUUID()}.staging`;
         if (await stat(finalDir).catch(() => undefined))
             throw new Error("tool directory already exists");
         try {
@@ -49,7 +67,7 @@ export class ToolRegistry {
             await rm(stagingDir, { recursive: true, force: true });
             throw error;
         }
-        const now = new Date().toISOString(), tool = { id: `tool_${crypto.randomUUID()}`, slug, name: input.name.trim(), description: input.description?.trim().slice(0, 500), entrypoint, script, source: "user", enabled: true, createdAt: now, updatedAt: now };
+        const now = new Date().toISOString(), tool = { id: `tool_${crypto.randomUUID()}`, slug, name: input.name.trim(), description: input.description?.trim().slice(0, 500), entrypoint, script, environment, permissions, source: "user", enabled: true, createdAt: now, updatedAt: now };
         this.items.push(tool);
         try {
             await this.save();
@@ -67,6 +85,45 @@ export class ToolRegistry {
         return undefined; const root = join(this.toolsDir, tool.slug), file = resolve(root, resource ? safeRelative(resource) : tool.entrypoint); if (!inside(root, file))
         throw new Error("tool resource must stay inside the tool directory"); const info = await stat(file).catch(() => undefined); if (!info?.isFile())
         throw new Error("tool file does not exist"); return { tool: copy(tool), file, root }; }
+    /**
+     * THE EXPORT, AND THE ONLY PRODUCER OF A SHAREABLE BUNDLE.
+     *
+     * The client cannot assemble one (it never receives file content), and there is no CLI, script, or
+     * agent path on purpose: handing out a tool's source is something a person clicks.
+     *
+     * The bundle is FLAT, so the exported file is itself a valid `tool_register` payload - the same
+     * shape `POST /api/tools` takes. Nothing machine-local travels: no id (a fresh one is minted on
+     * import), no timestamps, and no way to reach Super Pi. A tool addresses its own runtime RELATIVELY
+     * (`./api/run`), the server derives which tool that is from the mount URL, and `SUPER_PI_TOOL_ID`
+     * is handed to Python at run time - so there is no binding inside the files that an import would
+     * have to rewrite, and nothing to leak when the file travels.
+     */
+    async exportBundle(id) {
+        await this.load();
+        const tool = this.items.find((x) => x.id === id);
+        if (!tool)
+            return undefined;
+        const root = join(this.toolsDir, tool.slug);
+        const files = [], skipped = [];
+        await collectAssets(root, root, files, skipped);
+        files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+        return {
+            bundle: {
+                format: EXPORT_FORMAT,
+                version: EXPORT_VERSION,
+                exportedAt: new Date().toISOString(),
+                slug: tool.slug,
+                name: tool.name,
+                ...(tool.description ? { description: tool.description } : {}),
+                entrypoint: tool.entrypoint,
+                files,
+                ...(tool.script ? { script: tool.script } : {}),
+                ...(tool.environment ? { environment: tool.environment } : {}),
+                ...(tool.permissions?.llm ? { permissions: { llm: true } } : {}),
+            },
+            skipped: [...skipped].sort(),
+        };
+    }
 }
 function normalizeAssets(files) { const paths = new Set(); let bytes = 0; return files.map((item) => { if (!item || typeof item.content !== "string")
     throw new Error("tool file content must be text"); const path = safeRelative(item.path); if (paths.has(path))
@@ -75,6 +132,70 @@ function normalizeAssets(files) { const paths = new Set(); let bytes = 0; return
 function normalizeScript(script, files) { const path = safeRelative(script.path); if (!path.endsWith(".py") || !files.some((x) => x.path === path))
     throw new Error("script must name an included .py file"); if (script.parameters && Object.values(script.parameters).some((x) => !isParam(x)))
     throw new Error("script parameter schema is invalid"); return { path, timeoutMs: script.timeoutMs, parameters: script.parameters }; }
+/**
+ * THE PIN IS CHECKED HERE, ON THE WAY IN, AND A RANGE IS A REFUSAL RATHER THAN A WARNING.
+ * A warning would throw away exactly what the environment buys: by the time the user learned that
+ * `requests` had drifted, the tool had already been treated as runnable.
+ */
+function normalizeEnvironment(environment) {
+    if (environment.requires !== undefined) {
+        if (!Array.isArray(environment.requires))
+            throw new Error("environment.requires 必须是数组");
+        if (environment.requires.length > 64)
+            throw new Error("工具依赖过多（上限 64 个）");
+        environment.requires = environment.requires.map((item) => {
+            if (typeof item !== "string" || !PINNED_REQUIREMENT.test(item.trim()))
+                throw new Error(`依赖必须钉死到精确版本（写成 pkg==version）：${String(item).slice(0, 60)}`);
+            return item.trim();
+        });
+    }
+    if (environment.requiresPython !== undefined && (typeof environment.requiresPython !== "string" || !/^[\d.,<>=!~ ]{1,40}$/.test(environment.requiresPython)))
+        throw new Error("requiresPython 写法不合法，例如 >=3.10,<4");
+    return environment;
+}
+/** Only one permission exists, and only as a boolean. Anything else is DROPPED rather than stored, so a
+ *  typo in a bundle cannot become a capability nobody implemented - and cannot fail the whole import
+ *  either, which would make a stray key the difference between "installed" and "not". */
+function normalizePermissions(permissions) {
+    if (!permissions || typeof permissions !== "object")
+        return undefined;
+    const llm = permissions.llm === true;
+    return llm ? { llm: true } : undefined;
+}
+/**
+ * Walks the tool directory. TWO THINGS ARE SKIPPED, and neither may be dropped quietly, because a
+ * bundle is a file the user is about to hand to someone else:
+ *
+ *   - symlinks. `inside()` is a lexical check, so one link pointing out of the tool directory would
+ *     be followed and its content packed into the bundle.
+ *   - files that do not survive a utf8 round trip. The registry only ever writes text, but a
+ *     hand-placed binary would come back as mojibake and re-import as a different tool.
+ *
+ * Both are reported in `skipped` so the caller can name them.
+ */
+async function collectAssets(root, dir, files, skipped) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const target = join(dir, entry.name), path = relative(root, target).split(sep).join("/");
+        if (entry.isSymbolicLink()) {
+            skipped.push(path);
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await collectAssets(root, target, files, skipped);
+            continue;
+        }
+        if (!entry.isFile()) {
+            skipped.push(path);
+            continue;
+        }
+        const buffer = await readFile(target);
+        if (!Buffer.from(buffer.toString("utf8"), "utf8").equals(buffer)) {
+            skipped.push(path);
+            continue;
+        }
+        files.push({ path, content: buffer.toString("utf8") });
+    }
+}
 async function writeAssets(root, files) { for (const asset of files) {
     const target = resolve(root, asset.path);
     if (!inside(root, target))
@@ -86,5 +207,7 @@ function safeRelative(value) { const p = value.replace(/\\/g, "/").trim(); if (!
     throw new Error("path must be relative and must not escape the tool directory"); return p; }
 function inside(root, target) { const r = relative(resolve(root), resolve(target)); return r === "" || (!r.startsWith(`..${sep}`) && r !== ".." && !r.includes(":")); }
 function isParam(value) { const x = value; return !!x && typeof x === "object" && ["string", "number", "boolean", "object", "array"].includes(x.type ?? "") && (x.required === undefined || typeof x.required === "boolean") && (x.enum === undefined || Array.isArray(x.enum)); }
-function isTool(value) { const x = value; return !!x && typeof x === "object" && typeof x.id === "string" && typeof x.slug === "string" && typeof x.name === "string" && typeof x.entrypoint === "string" && (x.source === "user" || x.source === "builtin"); }
-function copy(value) { return { ...value, script: value.script ? { ...value.script, parameters: value.script.parameters ? { ...value.script.parameters } : undefined } : undefined }; }
+function isTool(value) { const x = value; if (!x || typeof x !== "object" || typeof x.id !== "string" || typeof x.slug !== "string" || typeof x.name !== "string" || typeof x.entrypoint !== "string" || (x.source !== "user" && x.source !== "builtin"))
+    return false; if (x.environment !== undefined && (typeof x.environment !== "object" || x.environment === null))
+    return false; return x.permissions === undefined || (typeof x.permissions === "object" && x.permissions !== null); }
+function copy(value) { return { ...value, script: value.script ? { ...value.script, parameters: value.script.parameters ? { ...value.script.parameters } : undefined } : undefined, environment: value.environment ? { ...value.environment, requires: value.environment.requires ? [...value.environment.requires] : undefined } : undefined, permissions: value.permissions ? { ...value.permissions } : undefined }; }

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

@@ -1,3 +1,4 @@
+import type { ToolEnvironment, ToolFingerprint } from "./tool-registry.js";
 export type ToolParameter = {
     type: "string" | "number" | "boolean" | "object" | "array";
     required?: boolean;
@@ -18,18 +19,87 @@ export type ToolRun = {
     result?: Record<string, unknown>;
     error?: string;
 };
+/** Which interpreter a run will use. THE ONLY PLACE THAT DECISION IS MADE. */
+export type PythonChoice = {
+    path: string;
+    kind: "tool-env" | "override" | "system";
+};
+/** What this machine has, MEASURED rather than assumed - it is what every tool's fingerprint is compared against. */
+export type LocalPython = PythonChoice & ToolFingerprint;
+/**
+ * WHAT THE TOOL LIST SHOWS NEXT TO EACH TOOL.
+ *
+ * `differs` is the interesting one: it does NOT block the tool (decision 6 in docs/TOOL-SHARING.md).
+ * An environment mismatch is usually harmless - a patch release, a different platform - and refusing
+ * would make a working tool unusable. This value's job is to say what is true, not to gate.
+ */
+export type ToolEnvironmentState = {
+    state: "zero-deps" | "ready" | "needs-python" | "needs-env" | "differs";
+    python?: string;
+    platform?: string;
+    requires?: string[];
+    detail?: string;
+};
 /** Runs a registered Python entrypoint without a shell. It intentionally accepts no command string. */
 export declare class ToolRunner {
+    private readonly dataDir?;
     private readonly runs;
+    /** Optional so the existing unit tests can build a runner with no data dir; a tool that needs no venv never touches it. */
+    constructor(dataDir?: string | undefined);
+    /**
+     * THE RESOLUTION ORDER, IN ONE PLACE, AND IT IS AN ORDER ON PURPOSE.
+     *
+     *   1. the tool's own venv - a tool's dependencies belong to that tool and to nothing else;
+     *   2. `SUPER_PI_PYTHON_COMMAND` - the user's explicit choice, already honoured before this existed;
+     *   3. the system interpreter - today's behaviour;
+     *   4. nothing usable, which is REPORTED as a sentence rather than discovered as an ENOENT.
+     *
+     * Bundling an interpreter later is a fourth rung on this chain, which is why nothing in a tool's
+     * files has to know about it.
+     */
+    resolvePython(toolId: string, needsVenv: boolean): PythonChoice;
+    /** The venv lives BESIDE the tools, not inside one: export walks the tool directory, and the mount route serves everything under it. */
+    envDir(toolId: string): string;
+    private envPython;
+    /** MEASURE this machine's Python. One spawn; the answer is what every fingerprint is compared to. */
+    describeLocalPython(): Promise<LocalPython | undefined>;
+    environmentState(tool: {
+        id: string;
+        environment?: ToolEnvironment;
+    }): Promise<ToolEnvironmentState>;
+    /**
+     * Starts a run. It RETURNS SYNCHRONOUSLY - so bad parameters still throw at the call site, exactly
+     * as before - while the interpreter and, if the tool needs one, its virtual environment are prepared
+     * in the background. The run is already `running` at that point and the build's output lands in the
+     * run's own `logs`, which is why the tool's existing dialog shows the progress without knowing
+     * anything about environments.
+     */
     start(input: {
         toolId: string;
         script: string;
         cwd: string;
         definition: ToolScript;
         params: Record<string, unknown>;
+        environment?: ToolEnvironment;
     }): ToolRun;
+    private prepare;
+    /**
+     * THE VENV IS PYTHON'S OWN, ON PURPOSE. `python -m venv` finds its site-packages through the
+     * pyvenv.cfg next to the interpreter, which is why it survives the `-I` a tool runs under - a
+     * PYTHONPATH-based vendor directory does not (verified: `-I` implies `-E`, so PYTHONPATH is
+     * ignored, and dropping `-I` would give up the isolation that keeps a hostile PYTHON* environment
+     * from influencing a shared tool's script).
+     */
+    private ensureEnvironment;
+    private launch;
     get(id: string, toolId: string): ToolRun | undefined;
     cancel(id: string, toolId: string): ToolRun | undefined;
     private finish;
 }
+/**
+ * A SMALL, DELIBERATELY SMALL PEP 440 READER: `>=`, `>`, `<=`, `<`, `==`, comma-separated. Anything it
+ * cannot parse counts as NOT satisfied, because a version check that guesses is worse than one that
+ * refuses. A tool needing something exotic declares no range at all and relies on the venv, not here.
+ */
+export declare function satisfiesRange(version: string, range: string): boolean;
 export declare function validateParams(schema: Record<string, ToolParameter>, params: Record<string, unknown>): void;