@evandu/super-pi 0.1.85 → 0.1.86

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;

package/dist/server/tool-runner.js

@@ -1,23 +1,163 @@
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
+import { join } from "node:path";
 const MAX_LOG_BYTES = 512_000;
 const MAX_TIMEOUT_MS = 10 * 60_000;
+/** The environment build gets its OWN budget: a cold `pip install` must not eat the tool's timeout. */
+const MAX_ENV_TIMEOUT_MS = 10 * 60_000;
+const isWindows = process.platform === "win32";
 /** Runs a registered Python entrypoint without a shell. It intentionally accepts no command string. */
 export class ToolRunner {
+    dataDir;
     runs = new Map();
+    /** 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) {
+        this.dataDir = dataDir;
+    }
+    /**
+     * 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, needsVenv) {
+        if (needsVenv && this.dataDir) {
+            const envPython = this.envPython(toolId);
+            if (existsSync(envPython))
+                return { path: envPython, kind: "tool-env" };
+        }
+        const override = process.env.SUPER_PI_PYTHON_COMMAND?.trim();
+        if (override)
+            return { path: override, kind: "override" };
+        return { path: isWindows ? "python.exe" : "python3", kind: "system" };
+    }
+    /** The venv lives BESIDE the tools, not inside one: export walks the tool directory, and the mount route serves everything under it. */
+    envDir(toolId) { return join(this.dataDir ?? ".", "tool-envs", toolId); }
+    envPython(toolId) { return join(this.envDir(toolId), ".venv", isWindows ? "Scripts" : "bin", isWindows ? "python.exe" : "python"); }
+    /** MEASURE this machine's Python. One spawn; the answer is what every fingerprint is compared to. */
+    async describeLocalPython() {
+        const choice = this.resolvePython("", false);
+        const probe = await runCapture(choice.path, ["-I", "-c", "import json,platform,sys;print(json.dumps({'python':sys.version.split()[0],'platform':platform.system().lower()+'-'+platform.machine()}))"], 10_000);
+        if (!probe.ok)
+            return undefined;
+        try {
+            const parsed = JSON.parse(probe.stdout);
+            if (typeof parsed?.python !== "string")
+                return undefined;
+            return { ...choice, python: parsed.python, platform: parsed.platform };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async environmentState(tool) {
+        const environment = tool.environment;
+        const requires = environment?.requires ?? [];
+        const wants = requires.length > 0 || Boolean(environment?.requiresPython);
+        const local = await this.describeLocalPython();
+        const base = { python: local?.python, platform: local?.platform, requires };
+        if (!wants)
+            return { ...base, state: "zero-deps" };
+        if (!local)
+            return { ...base, state: "needs-python", detail: "这台机器上找不到可用的 Python 解释器。" };
+        if (environment?.requiresPython && !satisfiesRange(local.python ?? "", environment.requiresPython))
+            return { ...base, state: "needs-python", detail: `这个工具需要 Python ${environment.requiresPython}，本机是 ${local.python}。` };
+        if (requires.length > 0 && this.dataDir && !existsSync(this.envPython(tool.id)))
+            return { ...base, state: "needs-env", detail: "首次运行这个工具时会自动安装这些依赖。" };
+        const known = environment?.fingerprint;
+        if (known?.python && known.platform && (majorMinor(known.python) !== majorMinor(local.python ?? "") || known.platform !== local.platform))
+            return { ...base, state: "differs", detail: `导出方是 Python ${known.python} / ${known.platform}，本机是 ${local.python} / ${local.platform}。` };
+        return { ...base, state: "ready" };
+    }
+    /**
+     * 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) {
         validateParams(input.definition.parameters ?? {}, input.params);
-        const python = process.env.SUPER_PI_PYTHON_COMMAND?.trim() || (process.platform === "win32" ? "python.exe" : "python3");
         const id = `toolrun_${randomUUID()}`;
         const run = { id, toolId: input.toolId, status: "running", startedAt: new Date().toISOString(), logs: "" };
-        // -I ignores user Python configuration and user site packages. No shell means params never become code.
-        const child = spawn(python, ["-I", "-u", input.script], { cwd: input.cwd, shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"], env: { PATH: process.env.PATH, SystemRoot: process.env.SystemRoot, TEMP: process.env.TEMP, TMP: process.env.TMP, PYTHONIOENCODING: "utf-8", PYTHONNOUSERSITE: "1", SUPER_PI_TOOL_ID: input.toolId } });
-        const active = { run, child, stdout: "", cancelled: false, timer: setTimeout(() => this.finish(id, "timed_out", `脚本超过 ${boundedTimeout(input.definition.timeoutMs)}ms 时限`), boundedTimeout(input.definition.timeoutMs)) };
-        active.timer.unref();
+        const timer = setTimeout(() => this.finish(id, "timed_out", `准备运行环境超过 ${MAX_ENV_TIMEOUT_MS}ms 时限`), MAX_ENV_TIMEOUT_MS);
+        timer.unref();
+        const active = { run, stdout: "", cancelled: false, timer };
         this.runs.set(id, active);
-        const log = (data) => { active.run.logs = clipped(`${active.run.logs}${data.toString("utf8")}`); };
+        void this.prepare(id, active, input);
+        return copy(run);
+    }
+    async prepare(id, active, input) {
+        try {
+            const requires = input.environment?.requires ?? [];
+            let python = this.resolvePython(input.toolId, false);
+            if (requires.length > 0) {
+                const built = await this.ensureEnvironment(input.toolId, python, requires, active);
+                if (!built.ok) {
+                    this.finish(id, "failed", built.error);
+                    return;
+                }
+                python = { path: this.envPython(input.toolId), kind: "tool-env" };
+            }
+            if (active.cancelled)
+                return;
+            if (active.timer)
+                clearTimeout(active.timer);
+            const scriptTimer = setTimeout(() => this.finish(id, "timed_out", `脚本超过 ${boundedTimeout(input.definition.timeoutMs)}ms 时限`), boundedTimeout(input.definition.timeoutMs));
+            scriptTimer.unref();
+            active.timer = scriptTimer;
+            this.launch(id, active, python, input);
+        }
+        catch (error) {
+            this.finish(id, "failed", error instanceof Error ? error.message : "tool environment could not be prepared");
+        }
+    }
+    /**
+     * 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).
+     */
+    async ensureEnvironment(toolId, base, requires, active) {
+        if (!this.dataDir)
+            return { ok: false, error: "这个工具需要依赖，但没有可用的数据目录来存放它的虚拟环境。" };
+        const envDir = this.envDir(toolId), envPython = this.envPython(toolId);
+        const recorded = await readFile(join(envDir, "installed.json"), "utf8").then((text) => { try {
+            return JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        } }).catch(() => undefined);
+        if (existsSync(envPython) && Array.isArray(recorded?.requires) && recorded.requires.length === requires.length && recorded.requires.every((item, index) => item === requires[index]))
+            return { ok: true };
+        await rm(envDir, { recursive: true, force: true });
+        await mkdir(envDir, { recursive: true });
+        const requirements = join(envDir, "requirements.txt");
+        await writeFile(requirements, `${requires.join("\n")}\n`, "utf8");
+        logLine(active, `正在准备 Python 虚拟环境（${requires.join("、")}）…\n`);
+        const created = await runCapture(base.path, ["-m", "venv", join(envDir, ".venv")], MAX_ENV_TIMEOUT_MS, (text) => logLine(active, text));
+        if (!created.ok)
+            return { ok: false, error: `创建 Python 虚拟环境失败：${created.error || `解释器 ${base.path} 不可用`}` };
+        const installed = await runCapture(envPython, ["-m", "pip", "install", "--disable-pip-version-check", "--no-input", "-r", requirements], MAX_ENV_TIMEOUT_MS, (text) => logLine(active, text));
+        if (!installed.ok)
+            return { ok: false, error: `安装工具依赖失败：${installed.error || `pip 退出码 ${installed.code}`}（依赖：${requires.join("、")}）` };
+        await writeFile(join(envDir, "installed.json"), JSON.stringify({ requires, python: base.path, builtAt: new Date().toISOString() }, null, 2), "utf8");
+        return { ok: true };
+    }
+    launch(id, active, python, input) {
+        // -I ignores user Python configuration and user site packages. No shell means params never become code.
+        const child = spawn(python.path, ["-I", "-u", input.script], { cwd: input.cwd, shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"], env: { PATH: process.env.PATH, SystemRoot: process.env.SystemRoot, TEMP: process.env.TEMP, TMP: process.env.TMP, PYTHONIOENCODING: "utf-8", PYTHONNOUSERSITE: "1", SUPER_PI_TOOL_ID: input.toolId } });
+        active.child = child;
         child.stdout.on("data", (data) => { active.stdout = clipped(`${active.stdout}${data.toString("utf8")}`); });
-        child.stderr.on("data", log);
+        child.stderr.on("data", (data) => logLine(active, data.toString("utf8")));
         child.once("error", (error) => this.finish(id, "failed", error.message));
         child.once("close", (code) => {
             if (active.run.status !== "running")
@@ -38,7 +178,6 @@ export class ToolRunner {
             }
         });
         child.stdin.end(JSON.stringify(input.params));
-        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)
@@ -47,17 +186,78 @@ export class ToolRunner {
         this.finish(id, "cancelled");
     } return copy(active.run); }
     finish(id, status, error) { const active = this.runs.get(id); if (!active || active.run.status !== "running")
-        return; clearTimeout(active.timer); if (status !== "succeeded" && active.stdout)
+        return; if (active.timer)
+        clearTimeout(active.timer); if (status !== "succeeded" && active.stdout)
         active.run.logs = clipped(`${active.run.logs}${active.stdout}`); active.run.status = status; active.run.finishedAt = new Date().toISOString(); if (error)
-        active.run.error = error; if (!active.child.killed) {
+        active.run.error = error; if (active.child && !active.child.killed) {
         try {
             active.child.kill();
         }
         catch { }
     } }
 }
+/**
+ * Runs a Python process with NO SHELL - the same rule as a tool run, because what is being installed
+ * is code too. There is no command string anywhere on this path, only an argv.
+ */
+function runCapture(python, args, timeoutMs, onOutput) {
+    return new Promise((resolve) => {
+        let stdout = "", stderr = "", settled = false;
+        const child = spawn(python, args, { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "pipe"], env: { PATH: process.env.PATH, SystemRoot: process.env.SystemRoot, TEMP: process.env.TEMP, TMP: process.env.TMP, PYTHONIOENCODING: "utf-8", PYTHONNOUSERSITE: "1" } });
+        const timer = setTimeout(() => { if (settled)
+            return; settled = true; try {
+            child.kill();
+        }
+        catch { } resolve({ ok: false, code: null, stdout, error: `timed out after ${timeoutMs}ms` }); }, timeoutMs);
+        timer.unref();
+        child.stdout.on("data", (data) => { const text = data.toString("utf8"); stdout += text; onOutput?.(text); });
+        child.stderr.on("data", (data) => { const text = data.toString("utf8"); stderr += text; onOutput?.(text); });
+        child.once("error", (error) => { if (settled)
+            return; settled = true; clearTimeout(timer); resolve({ ok: false, code: null, stdout, error: error.message }); });
+        child.once("close", (code) => { if (settled)
+            return; settled = true; clearTimeout(timer); if (code === 0)
+            resolve({ ok: true, stdout, code });
+        else
+            resolve({ ok: false, code, stdout, error: stderr.split("\n").filter((line) => line.trim()).slice(-4).join("\n") }); });
+    });
+}
+/**
+ * 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 function satisfiesRange(version, range) {
+    const actual = version.split(".").map((part) => Number.parseInt(part, 10));
+    if (actual.some((part) => Number.isNaN(part)))
+        return false;
+    for (const term of range.split(",")) {
+        const match = /^(>=|<=|==|>|<)?\s*(\d+(?:\.\d+)*)$/.exec(term.trim());
+        if (!match)
+            return false;
+        const comparison = compareVersions(actual, match[2].split(".").map((part) => Number.parseInt(part, 10)));
+        const operator = match[1] ?? "==";
+        if (operator === ">=" && comparison < 0)
+            return false;
+        if (operator === ">" && comparison <= 0)
+            return false;
+        if (operator === "<=" && comparison > 0)
+            return false;
+        if (operator === "<" && comparison >= 0)
+            return false;
+        if (operator === "==" && comparison !== 0)
+            return false;
+    }
+    return true;
+}
+function compareVersions(left, right) { for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const a = left[index] ?? 0, b = right[index] ?? 0;
+    if (a !== b)
+        return a < b ? -1 : 1;
+} return 0; }
+function majorMinor(version) { return version.split(".").slice(0, 2).join("."); }
 function boundedTimeout(value) { return Math.max(1_000, Math.min(MAX_TIMEOUT_MS, Number.isFinite(value) ? Math.floor(value) : 60_000)); }
 function clipped(text) { return text.length > MAX_LOG_BYTES ? text.slice(-MAX_LOG_BYTES) : text; }
+function logLine(active, text) { active.run.logs = clipped(`${active.run.logs}${text}`); }
 function copy(run) { return { ...run, result: run.result ? { ...run.result } : undefined }; }
 export function validateParams(schema, params) {
     if (!params || Array.isArray(params) || typeof params !== "object")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evandu/super-pi",
-  "version": "0.1.85",
+  "version": "0.1.86",
   "description": "Web control plane and companion for Pi",
   "license": "MIT",
   "type": "module",
@@ -90,6 +90,9 @@
     "scripts/knowledge-base.test.mjs",
     "scripts/tool-runner.test.mjs",
     "scripts/tool-runtime-api.test.mjs",
+    "scripts/tool-sharing.test.mjs",
+    "scripts/tool-env.test.mjs",
+    "scripts/tool-llm.test.mjs",
     "scripts/extension-load.test.mjs",
     "scripts/static-client-assets.test.mjs",
     "scripts/cli.test.mjs",