promigence 0.1.0-beta.12

package/dist/mcp.js

@@ -0,0 +1,889 @@
+import { posix } from "node:path";
+import { DEFAULT_SNAPSHOT, PREVIEWS_UNAVAILABLE, PromigenceClient, PromigenceError, Sandbox, previewsFix, readCredentials, resolveSpendCap, } from "./sdk/index.js";
+import { forgetKeychainReads } from "./sdk/credstore.js";
+import { bool, clientOpts, execOutcome, outputTails, str } from "./commands.js";
+import { buildPrice, livePricing } from "./pricing.js";
+import { emit, errorEnvelope, errorTextLines, exitWith, forkSummary, noticeLine, parseUsd, toPromigenceError, usageError, write, } from "./io.js";
+import { VERSION } from "./surface.js";
+import { sh, shellArg } from "./term.js";
+export const MCP_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+export const MCP_OUTPUT_CAP = 16 * 1024;
+const READ_DEFAULT = 64 * 1024;
+const READ_CEILING = 1024 * 1024;
+const WAIT_DEFAULT_S = 100;
+const WAIT_CEILING_S = 600;
+const SIGNAL_GRACE_MS = 3_000;
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+function check(schema, args) {
+    for (const k of schema.required ?? []) {
+        if (args[k] === undefined)
+            return `missing required argument '${k}'`;
+    }
+    for (const [k, v] of Object.entries(args)) {
+        const p = schema.properties[k];
+        if (!p)
+            return `unknown argument '${k}'`;
+        if (v === undefined || v === null)
+            continue;
+        switch (p.type) {
+            case "string":
+                if (typeof v !== "string")
+                    return `'${k}' must be a string`;
+                if (p.enum && !p.enum.includes(v))
+                    return `'${k}' must be one of ${p.enum.join(" | ")}`;
+                if (p.pattern && !new RegExp(p.pattern).test(v))
+                    return `'${k}' is not valid (${p.description})`;
+                break;
+            case "integer":
+            case "number":
+                if (typeof v !== "number" || !Number.isFinite(v))
+                    return `'${k}' must be a number`;
+                if (p.type === "integer" && !Number.isInteger(v))
+                    return `'${k}' must be an integer`;
+                if (p.minimum !== undefined && v < p.minimum)
+                    return `'${k}' must be >= ${p.minimum}`;
+                if (p.maximum !== undefined && v > p.maximum)
+                    return `'${k}' must be <= ${p.maximum}`;
+                break;
+            case "boolean":
+                if (typeof v !== "boolean")
+                    return `'${k}' must be true or false`;
+                break;
+            case "array":
+                if (!Array.isArray(v) || v.some((x) => typeof x !== "string"))
+                    return `'${k}' must be an array of strings`;
+                break;
+            case "object":
+                if (typeof v !== "object" || Array.isArray(v) || Object.values(v).some((x) => typeof x !== "string")) {
+                    return `'${k}' must be an object of string values`;
+                }
+                break;
+        }
+    }
+    return undefined;
+}
+export function insideRoot(root, path, tool) {
+    const p = posix.normalize(path);
+    if (!path.startsWith("/"))
+        throw usageError(`${tool}: ${path} is not an absolute path`, "Pass an absolute path inside the sandbox.");
+    if (root === undefined || root === "/" || p === root || p.startsWith(`${root}/`))
+        return p;
+    throw usageError(`${tool}: ${path} is outside ${root}, the only directory this server's file tools may use (--root)`, `Name a path under ${root}.`);
+}
+const sandboxId = { type: "string", description: "The sandbox_id, e.g. sbx_01 (from sandbox_create or sandbox_list)." };
+const cwd = { type: "string", description: "Working directory inside the sandbox (absolute)." };
+const env = { type: "object", description: "Environment variables for this command.", additionalProperties: { type: "string" } };
+const network = { type: "string", description: "What the sandbox may reach: egress (default) or none.", enum: ["egress", "none"] };
+const allowHosts = { type: "array", description: "Run behind an outbound allow-list of these hosts, e.g. [\"github.com\", \"*.npmjs.org\"]. Not combinable with network=none.", items: { type: "string" } };
+const seconds = (what, extra = "") => ({ type: "integer", description: `${what} in seconds${extra}.`, minimum: 1 });
+function tail(text, cap = MCP_OUTPUT_CAP) {
+    return text.length <= cap ? { text, cut: false } : { text: text.slice(text.length - cap), cut: true };
+}
+const secondsToMs = (s) => (typeof s === "number" ? Math.round(s * 1000) : undefined);
+async function readTail(c, sid, eid, stream, have) {
+    const from = Math.max(0, have - MCP_OUTPUT_CAP);
+    const parts = [];
+    let at = from;
+    while (at < have) {
+        const r = await c.sandboxes.execs.read(sid, eid, stream, { offset: at, len: have - at });
+        if (r.data.length === 0)
+            break;
+        parts.push(r.data);
+        at += r.data.length;
+    }
+    return { text: Buffer.concat(parts).toString("utf8"), cut: from > 0 };
+}
+function execOutputPayload(rec, out, err) {
+    return {
+        exec_id: rec.exec_id,
+        sandbox_id: rec.sandbox_id,
+        state: rec.state,
+        exit_code: rec.exit?.exit_code ?? null,
+        signal: rec.exit?.signal ?? null,
+        stdout: out.text,
+        stderr: err.text,
+        truncated: out.cut || err.cut || Boolean(rec.truncated),
+        ...(rec.error ? { error: rec.error } : {}),
+    };
+}
+function reportSummary(report) {
+    const failed = (report.sandboxes ?? []).filter((s) => s.outcome !== "completed");
+    return {
+        run_id: report.run_id,
+        state: report.state,
+        ...(report.snapshot_id ? { snapshot_id: report.snapshot_id } : {}),
+        totals: report.totals,
+        ...(report.cost ? { cost: report.cost } : {}),
+        ...(report.grade ? { grade: report.grade } : {}),
+        fork: forkSummary(report.fork),
+        failed: failed.slice(0, 20).map((s) => ({
+            sandbox_id: s.sandbox_id,
+            outcome: s.outcome,
+            ...(s.failure ? { failure: s.failure } : {}),
+            ...(s.execs?.length ? { exit_code: s.execs[s.execs.length - 1].exit_code } : {}),
+        })),
+        ...(failed.length > 20 ? { failed_more: failed.length - 20 } : {}),
+        full_report: sh `promigence run report ${report.run_id} --json`,
+    };
+}
+export const MCP_TOOLS = [
+    {
+        name: "sandbox_create",
+        description: "Create a sandbox from a Promigence snapshot (id or alias; default promigence/base: Debian with Python 3.12, Node 24, Go, Docker, git, gcc and the Claude Code, Codex, Gemini and OpenCode CLIs) or from a container image (a tag, which the API pins, or NAME@sha256:…), and return its sandbox_id.",
+        readOnly: false,
+        inputSchema: {
+            type: "object",
+            properties: {
+                snapshot: { type: "string", description: "snap_<id>, an alias, or alias@commit7. Default promigence/base. Not with image." },
+                image: { type: "string", description: "a tag such as python:3.12 (the API pins it to a digest) or registry/name@sha256:<64 hex>. A new image's snapshot is built on first use (minutes, billed per second while it builds at its tier's rate: \`promigence pricing\`) and reused free after." },
+                tier: { type: "string", description: "Machine size for an image's snapshot; a snapshot already has one.", enum: ["xsmall", "small", "medium", "large-16", "large"] },
+                timeout_s: seconds("Sandbox lifetime", "; it is killed when this expires (default 15 minutes)"),
+                network,
+                allow_hosts: allowHosts,
+                env: { type: "object", description: "Environment variables applied to every command run in this sandbox.", additionalProperties: { type: "string" } },
+                cap_usd: { type: "number", description: "Spend cap in USD for this sandbox, a new image's build included; refused above it, nothing starts. Cannot exceed the server's --cap.", minimum: 0 },
+            },
+            additionalProperties: false,
+        },
+        async run(a, s) {
+            if (a["snapshot"] !== undefined && a["image"] !== undefined)
+                throw usageError("sandbox_create takes snapshot or image, not both", "Pass one of them.");
+            if (a["tier"] !== undefined && a["image"] === undefined)
+                throw usageError("tier applies to image only: a snapshot already has a tier", "Drop tier, or pass image.");
+            if (a["network"] === "none" && Array.isArray(a["allow_hosts"]) && a["allow_hosts"].length) {
+                throw usageError("allow_hosts cannot be combined with network=none", "Pass allow_hosts on its own: it already runs the sandbox behind an outbound allow-list.");
+            }
+            const asked = typeof a["cap_usd"] === "number" ? a["cap_usd"] : undefined;
+            const capped = asked !== undefined && s.cap !== undefined ? Math.min(asked, s.cap) : asked ?? s.cap;
+            const build = typeof a["image"] === "string" && capped !== undefined
+                ? (await buildPrice(s.client(), typeof a["tier"] === "string" ? a["tier"] : undefined)).most_usd
+                : 0;
+            let runCost = 0;
+            if (typeof a["image"] === "string" && capped !== undefined) {
+                const p = await livePricing(s.client());
+                const rate = p.tiers.find((t) => t.name === (typeof a["tier"] === "string" ? a["tier"] : "small"))?.per_second_usd ?? 0;
+                const seconds = Math.ceil((secondsToMs(a["timeout_s"]) ?? (p.view?.limits.default_timeout_s ?? 900) * 1000) / 1000);
+                runCost = rate * seconds;
+            }
+            if (typeof a["image"] === "string" && capped !== undefined && capped < build + runCost) {
+                const which = asked !== undefined && asked === capped ? "cap_usd" : "this server's --cap";
+                const needed = (Math.ceil((build + runCost) * 100) / 100).toFixed(2);
+                throw new PromigenceError({
+                    code: "cap_exceeded",
+                    message: `a new image's snapshot build can cost up to $${build.toFixed(2)}, over ${which} $${capped.toFixed(2)}` +
+                        `${capped >= build ? ` with the sandbox's own cost (about $${runCost.toFixed(2)})` : ""}; nothing was built or started`,
+                    fix: `Pass snapshot instead (build it once outside the agent: ${sh `promigence snapshot create --image ${a["image"]} --alias NAME`}), or ` +
+                        (which === "cap_usd" ? `pass cap_usd ${needed} or more.` : `start the server with --cap ${needed} or more.`),
+                    exitCode: 5,
+                });
+            }
+            const envs = a["env"];
+            const opts = { client: s.client() };
+            if (typeof a["snapshot"] === "string")
+                opts.snapshot = a["snapshot"];
+            if (typeof a["image"] === "string") {
+                opts.image = a["image"];
+                Object.assign(opts, { allowBuild: true });
+            }
+            if (typeof a["tier"] === "string")
+                opts.tier = a["tier"];
+            const timeoutMs = secondsToMs(a["timeout_s"]);
+            if (timeoutMs !== undefined)
+                opts.timeoutMs = timeoutMs;
+            if (a["network"] === "none")
+                opts.allowInternetAccess = false;
+            if (Array.isArray(a["allow_hosts"]) && a["allow_hosts"].length)
+                opts.allowHosts = a["allow_hosts"];
+            if (envs && Object.keys(envs).length)
+                opts.envs = envs;
+            if (capped !== undefined) {
+                opts.spendCap = capped;
+                if (opts.image !== undefined) {
+                    opts.onBuild = (b) => {
+                        const free = b.deduped === true || b.joined === true || b.idempotent_replay === true || b.state === "verified" || b.state === "built";
+                        const charged = free ? 0 : (typeof b.build_price === "number" ? b.build_price : build);
+                        opts.spendCap = Math.max(0, Math.round((capped - charged) * 1e9) / 1e9);
+                    };
+                }
+            }
+            const sb = await Sandbox.create(opts);
+            s.created.set(sb.sandboxId, envs && Object.keys(envs).length ? { envs } : {});
+            return {
+                sandbox_id: sb.sandboxId,
+                run_id: sb.runId,
+                snapshot: sb.snapshot,
+                state: "ready",
+                ...(timeoutMs === undefined ? {} : { timeout_s: Math.round(timeoutMs / 1000) }),
+                note: s.keep
+                    ? "Billed per second until sandbox_kill, sandbox_pause, or the timeout. Left running when this MCP session ends (--keep)."
+                    : "Billed per second until sandbox_kill, sandbox_pause, or the timeout. Killed when this MCP session ends.",
+            };
+        },
+    },
+    {
+        name: "sandbox_exec",
+        description: "Run a shell command in a sandbox and return its exit code, stdout and stderr; each stream keeps its last 16 KiB and `truncated` says when something was cut.",
+        readOnly: false,
+        inputSchema: {
+            type: "object",
+            properties: {
+                sandbox_id: sandboxId,
+                command: { type: "string", description: "The command, run by sh -c." },
+                cwd,
+                env,
+                timeout_s: seconds("Bound on the command", " (default 15 minutes)"),
+            },
+            required: ["sandbox_id", "command"],
+            additionalProperties: false,
+        },
+        async run(a, s) {
+            const sid = a["sandbox_id"];
+            const merged = { ...(s.created.get(sid)?.envs ?? {}), ...(a["env"] ?? {}) };
+            const timeoutMs = secondsToMs(a["timeout_s"]);
+            const r = await s.client().sandboxes.exec(sid, {
+                sh: a["command"],
+                ...(typeof a["cwd"] === "string" ? { cwd: a["cwd"] } : {}),
+                ...(Object.keys(merged).length ? { env: merged } : {}),
+                ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            });
+            const out = tail(r.stdout ?? "");
+            const err = tail(r.stderr ?? "");
+            const truncated = out.cut || err.cut || Boolean(r.truncated);
+            const o = execOutcome(r, sid, timeoutMs, "mcp");
+            return {
+                ...o.fields,
+                stdout: out.text,
+                stderr: err.text,
+                truncated,
+                exec_id: r.exec_id,
+                ...(o.error ? { error: { code: o.error.code, message: o.error.message, fix: o.error.fix } } : {}),
+                ...(truncated ? { full_output: sh `promigence exec output ${r.exec_id} --sandbox ${sid}` } : {}),
+            };
+        },
+    },
+    {
+        name: "sandbox_exec_background",
+        description: "Start a long-running command (a dev server, a watcher) in a sandbox and return its exec_id at once; read its output later with sandbox_exec_output.",
+        readOnly: false,
+        inputSchema: {
+            type: "object",
+            properties: {
+                sandbox_id: sandboxId,
+                command: { type: "string", description: "The command, run by sh -c." },
+                cwd,
+                env,
+                timeout_s: seconds("Bound on the command"),
+            },
+            required: ["sandbox_id", "command"],
+            additionalProperties: false,
+        },
+        async run(a, s) {
+            const sid = a["sandbox_id"];
+            const merged = { ...(s.created.get(sid)?.envs ?? {}), ...(a["env"] ?? {}) };
+            const timeoutMs = secondsToMs(a["timeout_s"]);
+            const rec = await s.client().sandboxes.execBackground(sid, {
+                sh: a["command"],
+                ...(typeof a["cwd"] === "string" ? { cwd: a["cwd"] } : {}),
+                ...(Object.keys(merged).length ? { env: merged } : {}),
+                ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            });
+            return { exec_id: rec.exec_id, sandbox_id: sid, state: rec.state, next: "sandbox_exec_output with this exec_id" };
+        },
+    },
+    {
+        name: "sandbox_exec_output",
+        description: "Fetch a background command's state, exit code and the last 16 KiB of its stdout and stderr; wait_s parks the call until it ends or the wait is spent.",
+        readOnly: true,
+        inputSchema: {
+            type: "object",
+            properties: {
+                sandbox_id: sandboxId,
+                exec_id: { type: "string", description: "The exec_id sandbox_exec_background returned." },
+                wait_s: { type: "integer", description: "Wait up to this long for the command to end before answering (default 0: answer now).", minimum: 0, maximum: 30 },
+            },
+            required: ["sandbox_id", "exec_id"],
+            additionalProperties: false,
+        },
+        async run(a, s) {
+            const c = s.client();
+            const sid = a["sandbox_id"];
+            const eid = a["exec_id"];
+            const waitMs = secondsToMs(a["wait_s"]);
+            const rec = await c.sandboxes.execs.get(sid, eid, waitMs ? { waitMs } : {});
+            const out = await readTail(c, sid, eid, "stdout", rec.stdout_bytes ?? 0);
+            const err = await readTail(c, sid, eid, "stderr", rec.stderr_bytes ?? 0);
+            return execOutputPayload(rec, out, err);
+        },
+    },
+    {
+        name: "sandbox_write_file",
+        description: "Write a file in a sandbox (text, or base64 for binary), creating or replacing it. A file that already exists keeps its mode (an executable script stays executable); a new one is 644 unless mode is given.",
+        readOnly: false,
+        inputSchema: {
+            type: "object",
+            properties: {
+                sandbox_id: sandboxId,
+                path: { type: "string", description: "Absolute path inside the sandbox." },
+                content: { type: "string", description: "The file's content." },
+                encoding: { type: "string", description: "How content is encoded: utf8 (default) or base64.", enum: ["utf8", "base64"] },
+                mode: { type: "string", description: "Permission bits in octal, e.g. 755 or 600. Default: keep an existing file's mode; 644 for a new file.", pattern: "^0?[0-7]{3,4}$" },
+            },
+            required: ["sandbox_id", "path", "content"],
+            additionalProperties: false,
+        },
+        async run(a, s) {
+            const sid = a["sandbox_id"];
+            const path = insideRoot(s.root, a["path"], "sandbox_write_file");
+            const data = a["encoding"] === "base64" ? Buffer.from(a["content"], "base64") : a["content"];
+            const mode = typeof a["mode"] === "string" ? parseInt(a["mode"], 8) : undefined;
+            const r = await s.client().sandboxes.files.put(sid, path, data, mode === undefined ? {} : { mode });
+            return { sandbox_id: sid, path: r.path ?? path, bytes: r.bytes, mode: r.mode };
+        },
+    },
+    {
+        name: "sandbox_read_file",
+        description: "Read a file from a sandbox as text (or base64 for binary), up to max_bytes (default 64 KiB, at most 1 MiB); use sandbox_exec with head, tail or grep for anything larger.",
+        readOnly: true,
+        inputSchema: {
+            type: "object",
+            properties: {
+                sandbox_id: sandboxId,
+                path: { type: "string", description: "Absolute path inside the sandbox." },
+                encoding: { type: "string", description: "How to return the content: utf8 (default) or base64.", enum: ["utf8", "base64"] },
+                max_bytes: { type: "integer", description: "Return at most this many bytes (default 65536, ceiling 1048576); `truncated` says when the file was longer.", minimum: 1, maximum: READ_CEILING },
+            },
+            required: ["sandbox_id", "path"],
+            additionalProperties: false,
+        },
+        async run(a, s) {
+            const c = s.client();
+            const sid = a["sandbox_id"];
+            const path = insideRoot(s.root, a["path"], "sandbox_read_file");
+            const max = typeof a["max_bytes"] === "number" ? a["max_bytes"] : READ_DEFAULT;
+            const { stat } = await c.sandboxes.files.stat(sid, path);
+            if (stat.is_dir)
+                throw usageError(`${path} is a directory`, "Call sandbox_list_files for a directory.");
+            if (stat.size > READ_CEILING) {
+                throw usageError(`${path} is ${stat.size} bytes; sandbox_read_file returns at most ${READ_CEILING}`, `Read a part of it with sandbox_exec (head, tail, sed -n), or copy it out with \`promigence files get ${shellArg(path)} ./local --sandbox ${shellArg(sid)}\`.`);
+            }
+            const bytes = await c.sandboxes.files.get(sid, path);
+            const slice = bytes.length > max ? bytes.subarray(0, max) : bytes;
+            const encoding = a["encoding"] === "base64" ? "base64" : "utf8";
+            return {
+                sandbox_id: sid,
+                path,
+                size: stat.size,
+                bytes: slice.length,
+                truncated: slice.length < bytes.length,
+                encoding,
+                content: encoding === "base64" ? Buffer.from(slice).toString("base64") : new TextDecoder().decode(slice),
+            };
+        },
+    },
+    {
+        name: "sandbox_list_files",
+        description: "List one directory level in a sandbox with the size and type of each entry.",
+        readOnly: true,
+        inputSchema: {
+            type: "object",
+            properties: {
+                sandbox_id: sandboxId,
+                path: { type: "string", description: "Absolute directory path inside the sandbox (default /)." },
+            },
+            required: ["sandbox_id"],
+            additionalProperties: false,
+        },
+        async run(a, s) {
+            const sid = a["sandbox_id"];
+            const path = insideRoot(s.root, typeof a["path"] === "string" ? a["path"] : (s.root ?? "/"), "sandbox_list_files");
+            const r = await s.client().sandboxes.files.list(sid, path);
+            return {
+                sandbox_id: sid,
+                path: r.path,
+                entries: r.entries.map((e) => ({ name: e.name, size: e.size, is_dir: e.is_dir, is_symlink: e.is_symlink, mode: e.mode })),
+                truncated: Boolean(r.truncated),
+            };
+        },
+    },
+    {
+        name: "sandbox_expose_port",
+        description: "Publish a port the sandbox listens on and return its preview URL; anyone holding the URL can reach the port until it is revoked or the sandbox ends. Preview URLs may not be available on this deployment (this beta): the error then names the SSH port forward that reaches the port instead.",
+        readOnly: false,
+        inputSchema: {
+            type: "object",
+            properties: {
+                sandbox_id: sandboxId,
+                port: { type: "integer", description: "The port a process inside the sandbox listens on.", minimum: 1, maximum: 65535 },
+            },
+            required: ["sandbox_id", "port"],
+            additionalProperties: false,
+        },
+        async run(a, s) {
+            const sid = a["sandbox_id"];
+            const port = a["port"];
+            let p;
+            try {
+                p = await s.client().sandboxes.ports.expose(sid, port);
+            }
+            catch (e) {
+                if (!(e instanceof PromigenceError) || e.message !== PREVIEWS_UNAVAILABLE)
+                    throw e;
+                throw new PromigenceError({ code: e.code, message: e.message, fix: previewsFix(sid, port), exitCode: e.cliExit });
+            }
+            return { sandbox_id: sid, port: p.port, url: p.url, revoke: sh `promigence port revoke ${p.port} --sandbox ${sid}` };
+        },
+    },
+    {
+        name: "sandbox_pause",
+        description: "Park a sandbox: it stops billing and keeps its state until sandbox_resume.",
+        readOnly: false,
+        inputSchema: { type: "object", properties: { sandbox_id: sandboxId }, required: ["sandbox_id"], additionalProperties: false },
+        async run(a, s) {
+            const r = await s.client().sandboxes.pause(a["sandbox_id"]);
+            return { sandbox_id: r.sandbox_id, state: r.state, ...(r.already_paused ? { already_paused: true } : {}) };
+        },
+    },
+    {
+        name: "sandbox_resume",
+        description: "Bring a paused sandbox back to ready; billing restarts.",
+        readOnly: false,
+        inputSchema: { type: "object", properties: { sandbox_id: sandboxId }, required: ["sandbox_id"], additionalProperties: false },
+        async run(a, s) {
+            const r = await s.client().sandboxes.resume(a["sandbox_id"]);
+            return { sandbox_id: r.sandbox_id, state: r.state };
+        },
+    },
+    {
+        name: "sandbox_kill",
+        description: "End a sandbox now: its files are gone and billing stops.",
+        readOnly: false,
+        destructive: true,
+        inputSchema: { type: "object", properties: { sandbox_id: sandboxId }, required: ["sandbox_id"], additionalProperties: false },
+        async run(a, s) {
+            const sid = a["sandbox_id"];
+            await s.client().sandboxes.kill(sid);
+            s.created.delete(sid);
+            return { sandbox_id: sid, killed: true };
+        },
+    },
+    {
+        name: "sandbox_list",
+        description: "List this org's sandboxes, newest first, optionally only those in one state.",
+        readOnly: true,
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "integer", description: "How many (default 50).", minimum: 1, maximum: 500 },
+                state: { type: "string", description: "Only this state, e.g. ready | running | paused | ended." },
+            },
+            additionalProperties: false,
+        },
+        async run(a, s) {
+            const all = await s.client().sandboxes.list(typeof a["limit"] === "number" ? a["limit"] : 50);
+            const rows = typeof a["state"] === "string" ? all.filter((x) => x.state === a["state"]) : all;
+            return {
+                sandboxes: rows.map((x) => ({
+                    sandbox_id: x.sandbox_id, state: x.state,
+                    ...(x.run_id ? { run_id: x.run_id } : {}),
+                    ...(x.snapshot_id ? { snapshot_id: x.snapshot_id } : {}),
+                    ...(s.created.has(x.sandbox_id) ? { created_here: true } : {}),
+                })),
+            };
+        },
+    },
+    {
+        name: "snapshot_list",
+        description: "List the snapshots available to fork: your org's (plus the public ones), or only the public examples with public=true.",
+        readOnly: true,
+        inputSchema: {
+            type: "object",
+            properties: { public: { type: "boolean", description: "Only the public example snapshots (no key needed)." } },
+            additionalProperties: false,
+        },
+        async run(a, s) {
+            const c = s.client();
+            const rows = a["public"] === true ? await c.snapshots.public(50) : await c.snapshots.list();
+            return {
+                snapshots: rows.map((x) => ({
+                    snapshot_id: x.snapshot_id,
+                    ...(x.alias ? { alias: x.alias } : {}),
+                    ...(x.visibility ? { visibility: x.visibility } : {}),
+                    ...(x.verified !== undefined ? { verified: x.verified } : {}),
+                    ...(x.tier_assigned ?? x.tier ? { tier: x.tier_assigned ?? x.tier } : {}),
+                    ...(x.repo ? { repo: x.repo } : {}),
+                    ...(x.commit ? { commit: x.commit } : {}),
+                    ...(x.source?.image ? { image: x.source.image } : {}),
+                })),
+            };
+        },
+    },
+    {
+        name: "run_batch",
+        description: "Fork a snapshot N times, run one shell command in every copy under a spend cap, wait (bounded by wait_s) and return the run_id with the validity report summary: environment failures (Promigence's, replayable) separated from task failures (the command's).",
+        readOnly: false,
+        inputSchema: {
+            type: "object",
+            properties: {
+                snapshot: { type: "string", description: "snap_<id>, an alias, or alias@commit7. Default promigence/base, as sandbox_create." },
+                command: { type: "string", description: "The command, run by sh -c in every sandbox." },
+                count: { type: "integer", description: "How many sandboxes to fork.", minimum: 1, maximum: 1000 },
+                cap_usd: { type: "number", description: "Spend cap in USD for the whole run; refused above it, nothing starts. Cannot exceed the server's --cap.", minimum: 0 },
+                timeout_s: seconds("Per-sandbox bound", " (default 15 minutes)"),
+                network,
+                allow_hosts: allowHosts,
+                wait_s: { type: "integer", description: `How long to wait for the run to finish before answering with its run_id (default ${WAIT_DEFAULT_S}, at most ${WAIT_CEILING_S}); the run keeps going and run_report reads it later.`, minimum: 1, maximum: WAIT_CEILING_S },
+            },
+            required: ["command", "count"],
+            additionalProperties: false,
+        },
+        async run(a, s) {
+            if (a["network"] === "none" && Array.isArray(a["allow_hosts"]) && a["allow_hosts"].length) {
+                throw usageError("allow_hosts cannot be combined with network=none", "Pass allow_hosts on its own: it already runs the sandbox behind an outbound allow-list.");
+            }
+            const c = s.client();
+            const asked = typeof a["cap_usd"] === "number" ? a["cap_usd"] : undefined;
+            const ceiling = asked !== undefined && s.cap !== undefined ? Math.min(asked, s.cap) : asked ?? s.cap;
+            const spendCap = await resolveSpendCap(c, ceiling);
+            const timeoutMs = secondsToMs(a["timeout_s"]);
+            const opts = {
+                snapshot: typeof a["snapshot"] === "string" ? a["snapshot"] : DEFAULT_SNAPSHOT,
+                count: a["count"],
+                spendCap,
+                exec: { sh: a["command"], killOnExit: true, ...(timeoutMs === undefined ? {} : { timeoutMs }) },
+            };
+            if (timeoutMs !== undefined)
+                opts.timeoutMs = timeoutMs;
+            if (a["network"] === "none")
+                opts.network = "none";
+            if (Array.isArray(a["allow_hosts"]) && a["allow_hosts"].length)
+                opts.network = { allow: a["allow_hosts"] };
+            const started = await c.runs.start(opts);
+            const runId = started.run_id;
+            s.runs.add(runId);
+            log(`run ${runId} started: ${started.sandboxes.length} sandboxes, cap ${spendCap} USD`);
+            const bound = (typeof a["wait_s"] === "number" ? a["wait_s"] : WAIT_DEFAULT_S) * 1000;
+            const waited = await c.runs.waitDone(runId, { waitTimeoutMs: bound });
+            if (waited.timedOut) {
+                return {
+                    run_id: runId,
+                    state: waited.run.state,
+                    spend_cap: spendCap,
+                    timed_out: true,
+                    note: `Still running after ${bound / 1000} s; nothing was killed. Call run_report with this run_id later.`,
+                };
+            }
+            s.runs.delete(runId);
+            const report = await c.runs.report(runId);
+            const tails = await outputTails(c, report.sandboxes ?? []);
+            return {
+                ...reportSummary(report),
+                spend_cap: spendCap,
+                outputs: [...tails].map(([sandbox_id, o]) => ({ sandbox_id, ...o })),
+                ...((report.sandboxes ?? []).filter((x) => x.execs?.length).length > tails.size
+                    ? { outputs_more: "the rest: sandbox_exec_output with the exec_id from run_report" }
+                    : {}),
+            };
+        },
+    },
+    {
+        name: "run_report",
+        description: "Fetch the validity report summary of a run by run_id: state, totals, cost, and every sandbox that did not complete.",
+        readOnly: true,
+        inputSchema: {
+            type: "object",
+            properties: { run_id: { type: "string", description: "The run_id run_batch returned." } },
+            required: ["run_id"],
+            additionalProperties: false,
+        },
+        async run(a, s) {
+            const report = await s.client().runs.report(a["run_id"]);
+            if (report.state !== "running")
+                s.runs.delete(report.run_id);
+            return reportSummary(report);
+        },
+    },
+];
+const log = (line) => { void write(process.stderr, `promigence mcp: ${line}\n`); };
+function rpcError(id, code, message, data) {
+    return { jsonrpc: "2.0", id, error: { code, message, ...(data === undefined ? {} : { data }) } };
+}
+function toolResult(s, payload, isError = false) {
+    const text = isError
+        ? `${payload["code"]}: ${payload["message"]}\nfix: ${payload["fix"]}`
+        : JSON.stringify(payload);
+    const structured = isError ? { error: payload } : payload;
+    return {
+        content: [{ type: "text", text }],
+        ...(s.protocolVersion === "2025-06-18" ? { structuredContent: structured } : {}),
+        ...(isError ? { isError: true } : {}),
+    };
+}
+function toolFailure(s, err) {
+    return toolResult(s, { code: err.code, message: err.message, fix: err.fix, docs: err.docs, guide: err.guide }, true);
+}
+function toolListing(t) {
+    return {
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+        annotations: { readOnlyHint: t.readOnly, destructiveHint: Boolean(t.destructive), openWorldHint: true },
+    };
+}
+export function instructions(readOnly, keep, root) {
+    return [
+        "Promigence gives you cloud sandboxes. sandbox_create makes one from a snapshot or a pinned container image; sandbox_exec runs shell commands in it; sandbox_write_file and sandbox_read_file move files; sandbox_kill ends it. A sandbox bills per second until it is killed, paused or times out.",
+        keep ? "Sandboxes created here are left running when this session ends." : "Every sandbox created here is killed when this session ends.",
+        "run_batch forks a snapshot N times, runs one command in every copy under a spend cap, and returns the run_id with a validity report summary in which environment failures (Promigence's, replayable) are separated from task failures (the command's).",
+        ...(readOnly ? ["This server is read-only: only the tools that list, read and report are offered; reading is still reading, so what a sandbox holds can be returned to you."] : []),
+        ...(root ? [`The file tools (sandbox_read_file, sandbox_write_file, sandbox_list_files) work only under ${root}.`] : []),
+        "A sandbox reaches the internet unless it was created with network=none or allow_hosts: keep credentials out of files a tool here can read, and create sandboxes that handle them with network=none or allow_hosts.",
+    ].join(" ");
+}
+const mcp = async (ctx) => {
+    let cap;
+    let allow;
+    let root;
+    try {
+        const rootFlag = str(ctx, "--root");
+        if (rootFlag !== undefined) {
+            if (!rootFlag.startsWith("/"))
+                throw usageError(`--root ${rootFlag} is not an absolute path`, "Pass a directory inside the sandbox, e.g. --root /work.");
+            root = posix.normalize(rootFlag).replace(/(.)\/+$/, "$1");
+        }
+        const capFlag = str(ctx, "--cap");
+        if (capFlag !== undefined)
+            cap = parseUsd(capFlag, "--cap");
+        const allowFlag = str(ctx, "--allow-tools");
+        if (allowFlag !== undefined) {
+            allow = new Set(allowFlag.split(",").map((x) => x.trim()).filter(Boolean));
+            const known = new Set(MCP_TOOLS.map((t) => t.name));
+            const unknown = [...allow].filter((x) => !known.has(x));
+            if (unknown.length)
+                throw usageError(`--allow-tools: unknown tool ${unknown.join(", ")}`, `Tools: ${[...known].join(", ")}.`);
+            if (allow.size === 0)
+                throw usageError("--allow-tools names no tool", "Pass --allow-tools sandbox_create,sandbox_exec,sandbox_kill.");
+        }
+    }
+    catch (err) {
+        const e = toPromigenceError(err);
+        return emit("text", errorEnvelope(ctx.cmd.name, e, []), errorTextLines(ctx.cmd.name, e, e.cliExit, []), e.cliExit, false);
+    }
+    const readOnly = bool(ctx, "--read-only");
+    const keep = bool(ctx, "--keep");
+    const offered = MCP_TOOLS.filter((t) => (!readOnly || t.readOnly) && (!allow || allow.has(t.name)));
+    const byName = new Map(offered.map((t) => [t.name, t]));
+    const orgs = new WeakMap();
+    const orgOf = (c) => {
+        let p = orgs.get(c);
+        if (!p) {
+            p = c.me().then((m) => m.org_id, () => undefined);
+            orgs.set(c, p);
+        }
+        return p;
+    };
+    const freshClient = () => new PromigenceClient({
+        ...clientOpts(ctx),
+        onNotice: (n) => log(noticeLine(n)),
+    });
+    let cached;
+    let cachedFrom = "";
+    const keyGiven = ctx.apiKey !== undefined || Boolean(process.env["PROMIGENCE_API_KEY"]?.trim());
+    const session = {
+        client: () => {
+            if (keyGiven)
+                return (cached ??= freshClient());
+            forgetKeychainReads();
+            const from = JSON.stringify(readCredentials());
+            if (cached && from === cachedFrom)
+                return cached;
+            cached = freshClient();
+            cachedFrom = from;
+            return cached;
+        },
+        cap,
+        keep,
+        created: new Map(),
+        runs: new Set(),
+        protocolVersion: MCP_PROTOCOL_VERSIONS[0],
+        root,
+    };
+    const inflight = new Set();
+    let closing = false;
+    const send = (msg) => {
+        if (closing)
+            return;
+        process.stdout.write(JSON.stringify(msg) + "\n");
+    };
+    const callTool = async (params) => {
+        const p = (params ?? {});
+        const name = typeof p.name === "string" ? p.name : "";
+        const tool = byName.get(name);
+        if (!tool) {
+            return toolFailure(session, usageError(`unknown tool '${name}'`, `Call tools/list; this server offers ${[...byName.keys()].join(", ")}${readOnly ? " (--read-only)" : ""}.`));
+        }
+        const c = session.client();
+        if (c.authenticated) {
+            const org = await orgOf(c);
+            if (session.org === undefined)
+                session.org = org;
+            else if (org !== undefined && org !== session.org) {
+                return toolFailure(session, new PromigenceError({
+                    code: "usage",
+                    message: `the credentials now belong to another organization (${org}); this MCP session started in ${session.org} and does not follow an org switch`,
+                    fix: "Ask the user to restart the MCP server to work in the new organization. Sandboxes this session started in the first one keep running until killed or their timeout (`promigence sandbox list` there).",
+                    exitCode: 2,
+                }));
+            }
+        }
+        if (!c.authenticated) {
+            return toolFailure(session, c.credentialsProblem ?? new PromigenceError({
+                code: "auth",
+                message: "no Promigence credentials: this MCP server found no API key (PROMIGENCE_API_KEY, --api-key or the credentials file)",
+                fix: "Ask the user to run `promigence login` in a terminal (or set PROMIGENCE_API_KEY in this server's environment), then call the tool again; no restart is needed.",
+                exitCode: 7,
+            }));
+        }
+        const args = (p.arguments && typeof p.arguments === "object" && !Array.isArray(p.arguments) ? p.arguments : {});
+        const bad = check(tool.inputSchema, args);
+        if (bad)
+            return toolFailure(session, usageError(`${name}: ${bad}`, `Follow the tool's inputSchema from tools/list.`));
+        try {
+            return toolResult(session, await tool.run(args, session));
+        }
+        catch (err) {
+            return toolFailure(session, toPromigenceError(err));
+        }
+    };
+    const dispatch = async (msg) => {
+        if (!msg || typeof msg !== "object" || Array.isArray(msg))
+            return rpcError(null, INVALID_REQUEST, "Invalid Request: not a JSON-RPC object");
+        const m = msg;
+        const id = typeof m.id === "string" || typeof m.id === "number" ? m.id : null;
+        if (typeof m.method !== "string") {
+            if (m.result !== undefined || m.error !== undefined)
+                return undefined;
+            return rpcError(id, INVALID_REQUEST, "Invalid Request: no method");
+        }
+        if (m.jsonrpc !== "2.0")
+            return rpcError(id, INVALID_REQUEST, "Invalid Request: jsonrpc must be \"2.0\"");
+        const notification = m.id === undefined;
+        if (notification)
+            return undefined;
+        switch (m.method) {
+            case "initialize": {
+                const asked = m.params?.protocolVersion;
+                session.protocolVersion = MCP_PROTOCOL_VERSIONS.includes(String(asked))
+                    ? asked
+                    : MCP_PROTOCOL_VERSIONS[0];
+                return {
+                    jsonrpc: "2.0", id,
+                    result: {
+                        protocolVersion: session.protocolVersion,
+                        capabilities: { tools: { listChanged: false } },
+                        serverInfo: { name: "promigence", title: "Promigence", version: VERSION },
+                        instructions: instructions(readOnly, keep, root),
+                    },
+                };
+            }
+            case "ping":
+                return { jsonrpc: "2.0", id, result: {} };
+            case "tools/list":
+                return { jsonrpc: "2.0", id, result: { tools: offered.map(toolListing) } };
+            case "tools/call": {
+                const p = m.params;
+                if (!p || typeof p !== "object" || typeof p.name !== "string")
+                    return rpcError(id, INVALID_PARAMS, "Invalid params: tools/call needs { name, arguments }");
+                return { jsonrpc: "2.0", id, result: await callTool(p) };
+            }
+            default:
+                return rpcError(id, METHOD_NOT_FOUND, `Method not found: ${m.method}`);
+        }
+    };
+    const handleLine = async (line) => {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            send(rpcError(null, PARSE_ERROR, "Parse error: not JSON"));
+            return;
+        }
+        if (Array.isArray(msg)) {
+            if (msg.length === 0)
+                return send(rpcError(null, INVALID_REQUEST, "Invalid Request: empty batch"));
+            const answers = (await Promise.all(msg.map(dispatch))).filter((r) => r !== undefined);
+            if (answers.length)
+                send(answers);
+            return;
+        }
+        const r = await dispatch(msg);
+        if (r)
+            send(r);
+    };
+    const track = (line) => {
+        const p = handleLine(line).catch((err) => log(`internal: ${err?.message ?? String(err)}`));
+        inflight.add(p);
+        void p.finally(() => inflight.delete(p));
+    };
+    const shutdown = async (reason, code, graceMs) => {
+        if (closing)
+            return new Promise(() => { });
+        closing = true;
+        process.stdin.pause();
+        const settled = Promise.allSettled([...inflight]);
+        await (graceMs === undefined ? settled : Promise.race([settled, new Promise((r) => setTimeout(r, graceMs))]));
+        const sandboxes = [...session.created.keys()];
+        const runs = [...session.runs];
+        if (keep) {
+            log(`${reason}; --keep: ${sandboxes.length} sandbox${sandboxes.length === 1 ? "" : "es"} and ${runs.length} run${runs.length === 1 ? "" : "s"} left running`);
+        }
+        else if (sandboxes.length || runs.length) {
+            const killAll = (c, sids, rids) => Promise.allSettled([
+                ...sids.map((sid) => c.sandboxes.kill(sid)),
+                ...rids.map((rid) => c.runs.kill(rid)),
+            ]);
+            const first = await killAll(session.client(), sandboxes, runs);
+            const again = (xs, off) => xs.filter((_, i) => first[off + i].status === "rejected");
+            const [sids, rids] = [again(sandboxes, 0), again(runs, sandboxes.length)];
+            const retried = sids.length || rids.length ? await killAll(freshClient(), sids, rids) : [];
+            const failed = retried.filter((r) => r.status === "rejected").length;
+            log(`${reason}; killed ${sandboxes.length} sandbox${sandboxes.length === 1 ? "" : "es"}, ${runs.length} run${runs.length === 1 ? "" : "s"}${failed ? ` (${failed} kill${failed === 1 ? "" : "s"} failed: promigence sandbox list)` : ""}`);
+        }
+        else {
+            log(reason);
+        }
+        return exitWith(code);
+    };
+    let buf = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+        buf += String(chunk);
+        let nl;
+        while ((nl = buf.indexOf("\n")) >= 0) {
+            const line = buf.slice(0, nl).trim();
+            buf = buf.slice(nl + 1);
+            if (line)
+                track(line);
+        }
+    });
+    process.stdin.on("end", () => {
+        const rest = buf.trim();
+        buf = "";
+        if (rest)
+            track(rest);
+        void shutdown("stdin closed", 0);
+    });
+    process.stdout.on("error", () => { void shutdown("stdout closed", 0, SIGNAL_GRACE_MS); });
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        process.on(sig, () => { void shutdown(`interrupted by ${sig}`, 130, SIGNAL_GRACE_MS); });
+    }
+    log(`serving ${offered.length} tool${offered.length === 1 ? "" : "s"} on stdio (promigence@${VERSION}${readOnly ? ", --read-only" : ""}${keep ? ", --keep" : ""}${cap === undefined ? "" : `, --cap ${cap}`})${session.client().authenticated ? "" : "; no credentials: every call will ask for `promigence login`"}`);
+    process.stdin.resume();
+    return new Promise(() => { });
+};
+export const MCP_HANDLERS = {
+    mcp,
+};