@evandu/super-pi 0.1.75 → 0.1.77

package/dist/client/index.html

@@ -8,7 +8,7 @@
     <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-Bi2QvT9i.js"></script>
+    <script type="module" crossorigin src="/assets/index-DiG980gH.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-CKdlMXJt.css">
   </head>
   <body>

package/dist/server/http-server.js

@@ -8,6 +8,7 @@ import { describe as describeFilesError, fileMeta, listDirectory, MAX_FILE_BYTES
 import { findUploadFile, MAX_UPLOAD_BODY_BYTES, saveUpload } from "./upload.js";
 import { checkDiskVersion } from "./version.js";
 import { gitDiff, gitLog, gitStatus } from "./git.js";
+import { verifyCapability } from "./capability.js";
 const MIME_TYPES = {
     ".css": "text/css; charset=utf-8",
     ".html": "text/html; charset=utf-8",
@@ -17,6 +18,41 @@ const MIME_TYPES = {
     ".ico": "image/x-icon",
     ".png": "image/png",
 };
+/**
+ * The only browser API a mounted tool needs.  It is served beneath the tool's own
+ * mount, so every request stays relative to that mount and the server can derive
+ * the tool identity without exposing a registry id, a workspace, or a credential.
+ */
+function toolBrowserSdk() {
+    return String.raw `(() => {
+  const request = async (path, init) => {
+    const response = await fetch(path, init);
+    let body;
+    try { body = await response.json(); } catch { body = { error: "Super Pi returned an unreadable response" }; }
+    if (!response.ok) throw new Error(body && body.error ? body.error : "Tool request failed (HTTP " + response.status + ")");
+    return body;
+  };
+  const api = {
+    run: (params = {}) => request("./api/run", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ params }) }),
+    get: (runId) => request("./api/runs/" + encodeURIComponent(runId), { method: "GET" }),
+    cancel: (runId) => request("./api/runs/" + encodeURIComponent(runId), { method: "DELETE" }),
+    wait: async (runId, { intervalMs = 250, signal } = {}) => {
+      for (;;) {
+        if (signal && signal.aborted) throw new DOMException("Aborted", "AbortError");
+        const run = await api.get(runId);
+        if (run.status !== "running") return run;
+        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 });
+        });
+      }
+    },
+    runAndWait: async (params = {}, options) => { const run = await api.run(params); return api.wait(run.id, options); },
+  };
+  Object.freeze(api);
+  Object.defineProperty(window, "SuperPiTool", { value: api, writable: false, configurable: false });
+})();`;
+}
 /**
  * Checks if the remote address is a local loopback interface.
  */
@@ -132,11 +168,14 @@ export function isAuthorized(request, accessToken) {
  */
 export function createHttpServer(options) {
     const { context, onShutdown } = options;
-    const { store, paths, accessToken, broadcaster, runService, catalogService, execService, toolRegistry } = context;
+    const { store, paths, accessToken, broadcaster, runService, catalogService, execService, toolRegistry, toolRunner } = context;
     const { uploadsDir, clientDir, rootDir } = paths;
     return createServer(async (request, response) => {
         // Internal tools use a narrow per-run capability, never the global management token.
-        if (request.url?.split("?")[0] !== "/api/memory/tool" && !isAuthorized(request, accessToken)) {
+        const requestPath = request.url?.split("?")[0] ?? "";
+        // Tool registration is checked after its JSON body is parsed: an agent proves its turn capability
+        // there, while an interactive browser uses the ordinary server access token.
+        if (requestPath !== "/api/memory/tool" && requestPath !== "/api/tools" && !requestPath.startsWith("/tools/") && !isAuthorized(request, accessToken)) {
             response.writeHead(401, { "www-authenticate": "Bearer" }).end("Authentication required");
             return;
         }
@@ -171,12 +210,22 @@ export function createHttpServer(options) {
                     }
                 }
                 const body = JSON.parse(raw);
-                const workspace = store.snapshot().workspaces.find((x) => x.id === body.workspaceId || (body.workspacePath && resolve(x.path) === resolve(body.workspacePath)));
-                if (!workspace || !body.slug || !body.name || !body.entrypoint) {
-                    json(400, { error: "workspaceId (or workspacePath), slug, name and entrypoint are required" });
+                if (!isAuthorized(request, accessToken)) {
+                    if (!body.conversationId) {
+                        json(401, { error: "authentication or agent capability required" });
+                        return;
+                    }
+                    const verdict = verifyCapability(body.conversationId, body.capability ?? request.headers["x-super-pi-capability"]);
+                    if (!verdict.ok) {
+                        json(403, { error: verdict.message });
+                        return;
+                    }
+                }
+                if (!body.slug || !body.name || !Array.isArray(body.files)) {
+                    json(400, { error: "slug, name and files are required" });
                     return;
                 }
-                const tool = await toolRegistry.register({ workspaceId: workspace.id, slug: body.slug, name: body.name, description: body.description, entrypoint: body.entrypoint }, workspace.path);
+                const tool = await toolRegistry.register({ slug: body.slug, name: body.name, description: body.description, entrypoint: body.entrypoint, script: body.script, files: body.files });
                 broadcaster.broadcast({ type: "tools.updated", tools: await toolRegistry.list() });
                 json(201, tool);
                 return;
@@ -195,13 +244,89 @@ export function createHttpServer(options) {
                 response.writeHead(404).end("Tool not found");
                 return;
             }
-            const workspace = store.snapshot().workspaces.find((x) => x.id === listed.workspaceId);
-            if (!workspace) {
-                response.writeHead(404).end("Workspace not found");
+            // A mounted tool never learns its random registry id.  Its API is instead addressed relative
+            // to its own mount (`./api/run`), and this route supplies that identity from the URL.  Besides
+            // making a generated tool usable on its first render, this binds status and cancellation to the
+            // same tool that created a run: an opaque frame for tool A cannot inspect tool B's run ids.
+            const toolOrigin = request.headers.origin === "null";
+            const toolApi = (status, body) => {
+                response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store", "access-control-allow-origin": "null", "vary": "Origin" });
+                response.end(JSON.stringify(body));
+            };
+            if (resource === "api/run") {
+                if (!toolOrigin) {
+                    toolApi(403, { error: "tool runtime API is only available to the sandboxed tool frame" });
+                    return;
+                }
+                if (request.method === "OPTIONS") {
+                    response.writeHead(204, { "access-control-allow-origin": "null", "access-control-allow-methods": "POST", "access-control-allow-headers": "content-type", "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);
+                    const resolved = await toolRegistry.resolve(id);
+                    if (!resolved?.tool.script) {
+                        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 ?? {} });
+                    toolApi(202, run);
+                }
+                catch (error) {
+                    toolApi(400, { error: error instanceof Error ? error.message : "tool run failed" });
+                }
+                return;
+            }
+            const runMatch = /^api\/runs\/([^/]+)$/.exec(resource);
+            if (runMatch) {
+                if (!toolOrigin) {
+                    toolApi(403, { error: "tool runtime API is only available to the sandboxed tool frame" });
+                    return;
+                }
+                if (request.method === "OPTIONS") {
+                    response.writeHead(204, { "access-control-allow-origin": "null", "access-control-allow-methods": "GET, DELETE", "vary": "Origin" }).end();
+                    return;
+                }
+                const runId = decodeURIComponent(runMatch[1]);
+                if (request.method === "GET") {
+                    const run = toolRunner.get(runId, id);
+                    if (!run) {
+                        toolApi(404, { error: "run not found" });
+                        return;
+                    }
+                    toolApi(200, run);
+                    return;
+                }
+                if (request.method === "DELETE") {
+                    const run = toolRunner.cancel(runId, id);
+                    if (!run) {
+                        toolApi(404, { error: "run 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;
             }
             try {
-                const resolved = await toolRegistry.resolve(id, workspace.path, resource);
+                const resolved = await toolRegistry.resolve(id, resource);
                 if (!resolved) {
                     response.writeHead(404).end("Tool not found");
                     return;

package/dist/server/index.js

@@ -23,6 +23,7 @@ import { createHttpServer, getLanIps, isLocalOrPrivateAddress, parseServerArgs }
 import { WsBroadcaster, WsServer } from "./ws-server.js";
 import { initRunningVersion } from "./version.js";
 import { ToolRegistry } from "./tool-registry.js";
+import { ToolRunner } from "./tool-runner.js";
 // ------------------------------------------------------------- Environment & paths
 const rootDir = resolve(import.meta.dirname, "../..");
 initRunningVersion(rootDir);
@@ -51,6 +52,7 @@ 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();
 const initialAgentDirs = resolveAgentDirectories({
     customDirs: store.snapshot().customAgentDirs,
     rootDir,
@@ -159,6 +161,7 @@ const serverContext = {
     catalogService,
     execService,
     toolRegistry,
+    toolRunner,
     terminalEnabled: () => terminalService.enabled,
     terminalDisabledReason: () => terminalDisabledReason(),
 };

package/dist/server/runtime.js

@@ -379,6 +379,7 @@ export class PiRpcRuntime {
         const { agents, problems } = await readAgents(this.agents.dir, { mode: "subagent" });
         for (const problem of problems)
             console.warn(`PiRpcRuntime: ${problem.file} is not a usable sub-agent - ${problem.message}`);
+        const capability = mintCapability(conversationId);
         return {
             [TASK_ENDPOINT_ENV]: this.options.endpoint ?? "",
             [TASK_EXEC_ENDPOINT_ENV]: this.options.execEndpoint ?? "",
@@ -389,11 +390,12 @@ export class PiRpcRuntime {
             [WORKFLOW_ENDPOINT_ENV]: this.options.workflowEndpoint ?? "",
             SUPER_PI_QUESTION_ENDPOINT: this.options.questionEndpoint ?? "",
             SUPER_PI_TOOLS_ENDPOINT: this.options.toolsEndpoint ?? "",
+            SUPER_PI_TOOLS_CAPABILITY: capability,
             // MINTED HERE, AT SPAWN, rather than read from anywhere: this is the only moment the value is
             // decided, so it cannot change underneath a running child. `SubagentSupervisor` never calls this
             // function, so no sub-agent process is ever handed a capability - which is what makes a sub-agent
             // unable to dispatch, however its allowlist is broken.
-            [TASK_CAPABILITY_ENV]: mintCapability(conversationId),
+            [TASK_CAPABILITY_ENV]: capability,
         };
     }
     async *answer({ conversation, prompt, signal, cwd, host, onPiQueue, onUserEntry, onSessionFile, onToolCall, onToolUpdate, onToolPreparing, onToolEnd, onThinking, images, memoryReview, memorySourceConversationId }) {

package/dist/server/server-context.d.ts

@@ -9,6 +9,7 @@ import type { ExtensionUiService } from "./application/extension-ui-service.js";
 import type { CatalogService } from "./application/catalog-service.js";
 import type { ExecService } from "./exec-service.js";
 import type { ToolRegistry } from "./tool-registry.js";
+import type { ToolRunner } from "./tool-runner.js";
 /**
  * Common filesystem paths used across the server.
  */
@@ -49,6 +50,7 @@ export interface ServerContext {
     catalogService: CatalogService;
     execService: ExecService;
     toolRegistry: ToolRegistry;
+    toolRunner: ToolRunner;
     /**
      * Whether the right rail's terminal tab should exist, and why not when it should not.
      *

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

@@ -1,18 +1,24 @@
+import type { ToolScript } from "./tool-runner.js";
+export type ToolAsset = {
+    path: string;
+    content: string;
+};
 export type MountedTool = {
     id: string;
     slug: string;
     name: string;
     description?: string;
-    workspaceId: string;
     entrypoint: string;
+    script?: ToolScript;
     source: "user" | "builtin";
     enabled: boolean;
     createdAt: string;
     updatedAt: string;
 };
+/** Global registry: a tool belongs to Super Pi, never to the workspace that created it. */
 export declare class ToolRegistry {
-    private readonly dataDir;
     private readonly file;
+    readonly toolsDir: string;
     private items;
     private loaded;
     constructor(dataDir: string);
@@ -20,16 +26,17 @@ export declare class ToolRegistry {
     private save;
     list(): Promise<MountedTool[]>;
     register(input: {
-        workspaceId: string;
         slug: string;
         name: string;
         description?: string;
-        entrypoint: string;
-    }, workspaceRoot: string): Promise<MountedTool>;
+        entrypoint?: string;
+        script?: ToolScript;
+        files: ToolAsset[];
+    }): Promise<MountedTool>;
     remove(id: string): Promise<boolean>;
-    setEnabled(id: string, enabled: boolean): Promise<MountedTool | undefined>;
-    resolve(id: string, workspaceRoot: string, resource?: string): Promise<{
+    resolve(id: string, resource?: string): Promise<{
         tool: MountedTool;
         file: string;
+        root: string;
     } | undefined>;
 }

package/dist/server/tool-registry.js

@@ -1,74 +1,90 @@
-import { mkdir, readFile, rename, writeFile, access, stat } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
-const MAX_TOOLS = 128;
-const MAX_SLUG = 64;
-const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const MAX_TOOLS = 128, MAX_ASSETS = 32, MAX_ASSET_BYTES = 512_000, SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** Global registry: a tool belongs to Super Pi, never to the workspace that created it. */
 export class ToolRegistry {
-    dataDir;
     file;
+    toolsDir;
     items = [];
     loaded = false;
-    constructor(dataDir) {
-        this.dataDir = dataDir;
-        this.file = join(dataDir, "tools.json");
+    constructor(dataDir) { this.file = join(dataDir, "tools.json"); this.toolsDir = join(dataDir, "tools"); }
+    async load() { if (this.loaded)
+        return; this.loaded = true; try {
+        const parsed = JSON.parse(await readFile(this.file, "utf8"));
+        if (Array.isArray(parsed))
+            this.items = parsed.filter(isTool);
     }
-    async load() {
-        if (this.loaded)
-            return;
-        this.loaded = true;
-        try {
-            const parsed = JSON.parse(await readFile(this.file, "utf8"));
-            if (Array.isArray(parsed))
-                this.items = parsed.filter(isTool);
-        }
-        catch {
-            this.items = [];
-        }
-    }
-    async save() {
-        await mkdir(this.dataDir, { recursive: true });
-        const tmp = `${this.file}.${process.pid}.tmp`;
-        await writeFile(tmp, JSON.stringify(this.items, null, 2), "utf8");
-        await rename(tmp, this.file);
-    }
-    async list() { await this.load(); return this.items.map((x) => ({ ...x })); }
-    async register(input, workspaceRoot) {
+    catch {
+        this.items = [];
+    } }
+    async save() { await mkdir(dirname(this.file), { recursive: true }); const tmp = `${this.file}.${process.pid}.tmp`; await writeFile(tmp, JSON.stringify(this.items, null, 2), "utf8"); await rename(tmp, this.file); }
+    async list() { await this.load(); return this.items.map(copy); }
+    async register(input) {
         await this.load();
         const slug = input.slug.trim().toLowerCase();
         if (!SLUG.test(slug))
-            throw new Error("slug 只能包含小写字母、数字和连字符");
+            throw new Error("slug must contain lowercase letters, digits, and hyphens only");
         if (!input.name.trim() || input.name.length > 120)
-            throw new Error("工具名称无效");
-        const entrypoint = safeRelative(input.entrypoint);
-        const root = resolve(workspaceRoot);
-        const file = resolve(root, entrypoint);
-        if (!isInside(root, file))
-            throw new Error("entrypoint 必须位于工作区内");
-        const info = await stat(file).catch(() => undefined);
-        if (!info?.isFile())
-            throw new Error("entrypoint 文件不存在");
-        if (!entrypoint.endsWith(".html"))
-            throw new Error("entrypoint 必须是 HTML 文件");
-        if (this.items.some((x) => x.workspaceId === input.workspaceId && x.slug === slug))
-            throw new Error("工具 slug 已存在");
+            throw new Error("tool name is invalid");
+        if (this.items.some((x) => x.slug === slug))
+            throw new Error("tool slug already exists");
         if (this.items.length >= MAX_TOOLS)
-            throw new Error("工具数量已达到上限");
-        const now = new Date().toISOString();
-        const tool = { id: `tool_${crypto.randomUUID()}`, slug, name: input.name.trim(), description: input.description?.trim().slice(0, 500), workspaceId: input.workspaceId, entrypoint, source: "user", enabled: true, createdAt: now, updatedAt: now };
+            throw new Error("tool limit reached");
+        if (!Array.isArray(input.files) || !input.files.length || input.files.length > MAX_ASSETS)
+            throw new Error("tool must contain 1-32 files");
+        const entrypoint = safeRelative(input.entrypoint ?? "index.html");
+        if (!entrypoint.endsWith(".html"))
+            throw new Error("entrypoint must be an HTML file");
+        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`;
+        if (await stat(finalDir).catch(() => undefined))
+            throw new Error("tool directory already exists");
+        try {
+            await writeAssets(stagingDir, files);
+            await rename(stagingDir, finalDir);
+        }
+        catch (error) {
+            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 };
         this.items.push(tool);
-        await this.save();
-        return { ...tool };
+        try {
+            await this.save();
+        }
+        catch (error) {
+            this.items.pop();
+            await rm(finalDir, { recursive: true, force: true });
+            throw error;
+        }
+        return copy(tool);
     }
-    async remove(id) { await this.load(); const before = this.items.length; this.items = this.items.filter((x) => x.id !== id); if (this.items.length !== before)
-        await this.save(); return before !== this.items.length; }
-    async setEnabled(id, enabled) { await this.load(); const item = this.items.find((x) => x.id === id); if (!item)
-        return undefined; item.enabled = enabled; item.updatedAt = new Date().toISOString(); await this.save(); return { ...item }; }
-    async resolve(id, workspaceRoot, resource = "") { await this.load(); const tool = this.items.find((x) => x.id === id && x.enabled); if (!tool)
-        return undefined; const root = resolve(workspaceRoot); const entrypoint = resolve(root, tool.entrypoint); if (!isInside(root, entrypoint))
-        return undefined; const file = resource ? resolve(dirname(entrypoint), safeRelative(resource)) : entrypoint; if (!isInside(dirname(entrypoint), file))
-        throw new Error("工具资源必须位于工具目录内"); await access(file).catch(() => { throw new Error("工具文件不存在"); }); return { tool: { ...tool }, file }; }
+    async remove(id) { await this.load(); const i = this.items.findIndex((x) => x.id === id); if (i < 0)
+        return false; const [tool] = this.items.splice(i, 1); await this.save(); await rm(join(this.toolsDir, tool.slug), { recursive: true, force: true }); return true; }
+    async resolve(id, resource = "") { await this.load(); const tool = this.items.find((x) => x.id === id && x.enabled); if (!tool)
+        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 }; }
 }
+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))
+    throw new Error(`duplicate tool file: ${path}`); paths.add(path); bytes += Buffer.byteLength(item.content); if (bytes > MAX_ASSET_BYTES)
+    throw new Error("tool files exceed 512KB"); return { path, content: item.content }; }); }
+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 }; }
+async function writeAssets(root, files) { for (const asset of files) {
+    const target = resolve(root, asset.path);
+    if (!inside(root, target))
+        throw new Error("tool file must stay inside its tool directory");
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, asset.content, "utf8");
+} }
 function safeRelative(value) { const p = value.replace(/\\/g, "/").trim(); if (!p || p.startsWith("/") || p.includes("\0") || p.split("/").includes(".."))
-    throw new Error("路径必须是工作区内的相对路径"); return p; }
-function isInside(root, target) { const r = relative(root, target); return r === "" || (!r.startsWith(".." + sep) && r !== ".." && !r.includes(":")); }
-function isTool(value) { const x = value; return !!x && typeof x === "object" && typeof x.id === "string" && typeof x.slug === "string" && typeof x.workspaceId === "string" && typeof x.entrypoint === "string" && (x.source === "user" || x.source === "builtin"); }
+    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 }; }

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

@@ -0,0 +1,35 @@
+export type ToolParameter = {
+    type: "string" | "number" | "boolean" | "object" | "array";
+    required?: boolean;
+    enum?: Array<string | number | boolean>;
+};
+export type ToolScript = {
+    path: string;
+    timeoutMs?: number;
+    parameters?: Record<string, ToolParameter>;
+};
+export type ToolRun = {
+    id: string;
+    toolId: string;
+    status: "running" | "succeeded" | "failed" | "cancelled" | "timed_out";
+    startedAt: string;
+    finishedAt?: string;
+    logs: string;
+    result?: Record<string, unknown>;
+    error?: string;
+};
+/** Runs a registered Python entrypoint without a shell. It intentionally accepts no command string. */
+export declare class ToolRunner {
+    private readonly runs;
+    start(input: {
+        toolId: string;
+        script: string;
+        cwd: string;
+        definition: ToolScript;
+        params: Record<string, unknown>;
+    }): ToolRun;
+    get(id: string, toolId: string): ToolRun | undefined;
+    cancel(id: string, toolId: string): ToolRun | undefined;
+    private finish;
+}
+export declare function validateParams(schema: Record<string, ToolParameter>, params: Record<string, unknown>): void;

package/dist/server/tool-runner.js

@@ -0,0 +1,81 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+const MAX_LOG_BYTES = 512_000;
+const MAX_TIMEOUT_MS = 10 * 60_000;
+/** Runs a registered Python entrypoint without a shell. It intentionally accepts no command string. */
+export class ToolRunner {
+    runs = new Map();
+    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();
+        this.runs.set(id, active);
+        const log = (data) => { active.run.logs = clipped(`${active.run.logs}${data.toString("utf8")}`); };
+        child.stdout.on("data", (data) => { active.stdout = clipped(`${active.stdout}${data.toString("utf8")}`); });
+        child.stderr.on("data", log);
+        child.once("error", (error) => this.finish(id, "failed", error.message));
+        child.once("exit", (code) => {
+            if (active.run.status !== "running")
+                return;
+            if (code !== 0) {
+                this.finish(id, "failed", `Python exited with code ${code ?? "unknown"}`);
+                return;
+            }
+            try {
+                const parsed = JSON.parse(active.stdout);
+                if (!parsed || Array.isArray(parsed) || typeof parsed !== "object")
+                    throw new Error("stdout must be a JSON object");
+                active.run.result = parsed;
+                this.finish(id, "succeeded");
+            }
+            catch (error) {
+                active.run.logs = clipped(`${active.run.logs}${active.stdout}`);
+                this.finish(id, "failed", `脚本没有输出一个 JSON 对象：${error instanceof Error ? error.message : "invalid output"}`);
+            }
+        });
+        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)
+        return undefined; if (active.run.status === "running") {
+        active.cancelled = true;
+        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); active.run.status = status; active.run.finishedAt = new Date().toISOString(); if (error)
+        active.run.error = error; if (!active.child.killed) {
+        try {
+            active.child.kill();
+        }
+        catch { }
+    } }
+}
+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 copy(run) { return { ...run, result: run.result ? { ...run.result } : undefined }; }
+export function validateParams(schema, params) {
+    if (!params || Array.isArray(params) || typeof params !== "object")
+        throw new Error("params 必须是对象");
+    for (const key of Object.keys(params))
+        if (!schema[key])
+            throw new Error(`不允许的参数：${key}`);
+    for (const [key, rule] of Object.entries(schema)) {
+        const value = params[key];
+        if (value === undefined) {
+            if (rule.required)
+                throw new Error(`缺少参数：${key}`);
+            continue;
+        }
+        const actual = Array.isArray(value) ? "array" : value === null ? "null" : typeof value;
+        if (actual !== rule.type)
+            throw new Error(`参数 ${key} 必须是 ${rule.type}`);
+        if (rule.enum && !rule.enum.includes(value))
+            throw new Error(`参数 ${key} 不在允许值中`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evandu/super-pi",
-  "version": "0.1.75",
+  "version": "0.1.77",
   "description": "Web control plane and companion for Pi",
   "license": "MIT",
   "type": "module",
@@ -84,6 +84,8 @@
     "scripts/agent-config-regression.test.mjs",
     "scripts/model-filter.test.mjs",
     "scripts/active-memory.test.mjs",
+    "scripts/tool-runner.test.mjs",
+    "scripts/tool-runtime-api.test.mjs",
     "scripts/extension-load.test.mjs"
   ],
   "check:browser": [