@evandu/super-pi 0.1.85 → 0.1.87

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.87",
   "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",