@sanlabs/sanbox-cli 0.0.1

package/README.md

@@ -0,0 +1,15 @@
+# Sanbox CLI
+
+Agent-facing CLI and local MCP server for creating Sanbox runs.
+
+```bash
+export SANBOX_API_URL=http://167.233.236.51
+export SANBOX_ORG=rheinfall-bank
+export SANBOX_API_KEY=sbx_live_...
+
+sanbox auth check
+sanbox run --task "Inspect the auth flow" --include "app/**" --wait --json
+sanbox batch --tasks tasks.json --include "app/**" --max-parallel 5 --wait --json
+```
+
+The package also exposes `sanbox-mcp`, a local stdio MCP server for tools such as Codex, Claude Code, Cursor, and Copilot.

package/dist/api.js

@@ -0,0 +1,59 @@
+export class SanboxApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+    }
+}
+export class SanboxClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async request(path, init = {}) {
+        const res = await fetch(`${this.config.apiUrl}${path}`, {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${this.config.apiKey}`,
+                "Content-Type": "application/json",
+                ...(init.headers || {})
+            }
+        });
+        const text = await res.text();
+        const body = text ? JSON.parse(text) : {};
+        if (!res.ok) {
+            const message = body && typeof body === "object" && "error" in body ? String(body.error) : res.statusText;
+            throw new SanboxApiError(message, res.status, body);
+        }
+        return body;
+    }
+    me() {
+        return this.request("/v1/me");
+    }
+    createRun(body) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs`, {
+            method: "POST",
+            body: JSON.stringify(body)
+        });
+    }
+    getRun(runId) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}`);
+    }
+    listEvents(runId, afterEventId = 0) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/events?after_event_id=${afterEventId}`);
+    }
+    cancelRun(runId) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/cancel`, {
+            method: "POST",
+            body: "{}"
+        });
+    }
+    sendMessage(runId, message, payload = {}) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/messages`, {
+            method: "POST",
+            body: JSON.stringify({ message, payload })
+        });
+    }
+}

package/dist/args.js

@@ -0,0 +1,46 @@
+const multiFlags = new Set(["include"]);
+export const parseArgs = (argv) => {
+    const command = [];
+    const flags = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg.startsWith("--")) {
+            command.push(arg);
+            continue;
+        }
+        const raw = arg.slice(2);
+        const eqIndex = raw.indexOf("=");
+        const key = eqIndex === -1 ? raw : raw.slice(0, eqIndex);
+        const inlineValue = eqIndex === -1 ? undefined : raw.slice(eqIndex + 1);
+        const value = inlineValue ?? (argv[index + 1] && !argv[index + 1].startsWith("--") ? argv[++index] : true);
+        if (multiFlags.has(key)) {
+            const existing = flags[key];
+            flags[key] = Array.isArray(existing) ? [...existing, String(value)] : [String(value)];
+        }
+        else {
+            flags[key] = value;
+        }
+    }
+    return { command, flags };
+};
+export const flagString = (flags, key, fallback = "") => {
+    const value = flags[key];
+    if (Array.isArray(value))
+        return value[0] || fallback;
+    if (value === undefined || value === true || value === false)
+        return fallback;
+    return String(value);
+};
+export const flagNumber = (flags, key, fallback) => {
+    const value = Number(flagString(flags, key));
+    return Number.isFinite(value) ? value : fallback;
+};
+export const flagList = (flags, key, fallback = []) => {
+    const value = flags[key];
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === "string")
+        return [value];
+    return fallback;
+};
+export const hasFlag = (flags, key) => Boolean(flags[key]);

package/dist/cli.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import { flagList, flagNumber, flagString, hasFlag, parseArgs } from "./args.js";
+import { SanboxClient } from "./api.js";
+import { defaultWorkloadId, readConfig } from "./config.js";
+import { printJson, printRun } from "./output.js";
+import { createRun, isTerminalRun, readTasks, runPool, stableBatchId, waitForRun } from "./runs.js";
+import { version } from "./version.js";
+const help = `Sanbox CLI
+
+Environment:
+  SANBOX_API_URL   Sanbox API base URL
+  SANBOX_ORG       Organization slug
+  SANBOX_API_KEY   Org API key
+
+Commands:
+  sanbox auth check [--json]
+  sanbox run --task "..." [--include "app/**"] [--wait] [--json]
+  sanbox run --dossier ./task.zip [--wait] [--json]
+  sanbox batch --tasks tasks.json [--include "app/**"] [--max-parallel 5] [--wait] [--json]
+  sanbox runs get <run-id> [--json]
+  sanbox runs events <run-id> [--after-event-id 0] [--json]
+  sanbox runs cancel <run-id> [--json]
+  sanbox runs message <run-id> --message "..." [--json]
+  sanbox init agent [--write]
+`;
+const agentInstructions = `# Sanbox Agent Integration
+
+Use Sanbox when a task is independent, long-running, risky to run locally, or can be split into parallel subtasks.
+
+Environment expected by the CLI:
+- SANBOX_API_URL
+- SANBOX_ORG
+- SANBOX_API_KEY
+
+Useful commands:
+\`\`\`bash
+sanbox auth check
+sanbox run --task "Investigate one focused task" --include "app/**" --wait --json
+sanbox batch --tasks .sanbox/tasks.json --include "app/**" --max-parallel 5 --wait --json
+sanbox runs get <run-id> --json
+sanbox runs events <run-id> --json
+sanbox runs message <run-id> --message "Summarize the retained output" --json
+\`\`\`
+
+Do not put secrets in dossiers. The CLI excludes common env and secret-like filenames by default.
+`;
+const cwd = () => process.cwd();
+const makeClient = (flags) => new SanboxClient(readConfig(flags));
+const commandRun = async (flags) => {
+    const client = makeClient(flags);
+    const task = flagString(flags, "task");
+    const dossierPath = flagString(flags, "dossier");
+    if (!task && !dossierPath)
+        throw new Error("--task or --dossier is required.");
+    let payload = await createRun(client, {
+        cwd: cwd(),
+        cliVersion: version,
+        task,
+        dossierPath,
+        include: flagList(flags, "include"),
+        externalRunId: flagString(flags, "external-run-id") || undefined,
+        workloadId: flagString(flags, "workload-id", defaultWorkloadId),
+        retentionTtlSeconds: flagNumber(flags, "retention-ttl-seconds", 86400)
+    });
+    if (hasFlag(flags, "wait")) {
+        payload = await waitForRun(client, payload.run.id, {
+            pollIntervalMs: flagNumber(flags, "poll-interval-ms", 2000),
+            timeoutSeconds: flagNumber(flags, "timeout-seconds", 1800)
+        });
+    }
+    if (hasFlag(flags, "json"))
+        printJson(payload);
+    else
+        printRun(payload);
+    if (hasFlag(flags, "wait") && isTerminalRun(payload.run) && payload.run.status !== "completed")
+        process.exitCode = 2;
+};
+const commandBatch = async (flags) => {
+    const tasksPath = flagString(flags, "tasks");
+    if (!tasksPath)
+        throw new Error("--tasks is required.");
+    const client = makeClient(flags);
+    const tasks = await readTasks(tasksPath);
+    const batchId = flagString(flags, "batch-id") || await stableBatchId(tasksPath);
+    const include = flagList(flags, "include");
+    const maxParallel = flagNumber(flags, "max-parallel", 5);
+    const wait = hasFlag(flags, "wait");
+    const results = await runPool(tasks, maxParallel, async (task, index) => {
+        let payload = await createRun(client, {
+            cwd: cwd(),
+            cliVersion: version,
+            task: task.task,
+            include: task.include || include,
+            externalRunId: task.external_run_id || `sanbox-batch-${batchId}-${index + 1}`,
+            workloadId: flagString(flags, "workload-id", defaultWorkloadId),
+            retentionTtlSeconds: flagNumber(flags, "retention-ttl-seconds", 86400)
+        });
+        if (wait) {
+            payload = await waitForRun(client, payload.run.id, {
+                pollIntervalMs: flagNumber(flags, "poll-interval-ms", 2000),
+                timeoutSeconds: flagNumber(flags, "timeout-seconds", 1800)
+            });
+        }
+        return payload;
+    });
+    const output = { batch_id: batchId, runs: results.map((result) => result.run), results };
+    if (hasFlag(flags, "json"))
+        printJson(output);
+    else
+        results.forEach(printRun);
+    if (wait && results.some((result) => result.run.status !== "completed"))
+        process.exitCode = 2;
+};
+const commandAuthCheck = async (flags) => {
+    const client = makeClient(flags);
+    const me = await client.me();
+    const org = client.config.org;
+    const organizations = Array.isArray(me.organizations)
+        ? me.organizations
+        : [];
+    const selected = organizations.find((item) => item.slug === org) || null;
+    const output = { ok: Boolean(selected), org, selected, me };
+    if (hasFlag(flags, "json"))
+        printJson(output);
+    else
+        process.stdout.write(selected ? `ok org=${org}\n` : `authenticated, but org ${org} is not visible\n`);
+    if (!selected)
+        process.exitCode = 2;
+};
+const commandRuns = async (command, flags) => {
+    const client = makeClient(flags);
+    const action = command[1];
+    const runId = command[2];
+    if (!action || !runId)
+        throw new Error("runs command requires an action and run id.");
+    if (action === "get") {
+        const payload = await client.getRun(runId);
+        if (hasFlag(flags, "json"))
+            printJson(payload);
+        else
+            printRun(payload);
+        return;
+    }
+    if (action === "events") {
+        const payload = await client.listEvents(runId, flagNumber(flags, "after-event-id", 0));
+        if (hasFlag(flags, "json"))
+            printJson(payload);
+        else
+            payload.events.forEach((event) => process.stdout.write(`${event.id} ${event.level} ${event.kind} ${event.message}\n`));
+        return;
+    }
+    if (action === "cancel") {
+        const payload = await client.cancelRun(runId);
+        if (hasFlag(flags, "json"))
+            printJson(payload);
+        else
+            printRun(payload);
+        return;
+    }
+    if (action === "message") {
+        const message = flagString(flags, "message");
+        if (!message)
+            throw new Error("--message is required.");
+        const payload = await client.sendMessage(runId, message);
+        if (hasFlag(flags, "json"))
+            printJson(payload);
+        else
+            printRun(payload);
+        return;
+    }
+    throw new Error(`Unknown runs action: ${action}`);
+};
+const commandInit = async (command, flags) => {
+    if (command[1] !== "agent")
+        throw new Error("Only `sanbox init agent` is supported.");
+    if (hasFlag(flags, "write")) {
+        const dir = path.join(cwd(), ".sanbox");
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, "agent.md"), agentInstructions, "utf8");
+        process.stdout.write(".sanbox/agent.md written\n");
+        return;
+    }
+    process.stdout.write(agentInstructions);
+};
+const main = async () => {
+    const { command, flags } = parseArgs(process.argv.slice(2));
+    if (command.length === 0 || hasFlag(flags, "help")) {
+        process.stdout.write(help);
+        return;
+    }
+    if (command[0] === "auth" && command[1] === "check")
+        return commandAuthCheck(flags);
+    if (command[0] === "run")
+        return commandRun(flags);
+    if (command[0] === "batch")
+        return commandBatch(flags);
+    if (command[0] === "runs")
+        return commandRuns(command, flags);
+    if (command[0] === "init")
+        return commandInit(command, flags);
+    throw new Error(`Unknown command: ${command.join(" ")}`);
+};
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,12 @@
+export const defaultApiUrl = "http://127.0.0.1:8788";
+export const defaultWorkloadId = "opencode-runner";
+export const readConfig = (flags = {}) => {
+    const apiUrl = String(flags["api-url"] || process.env.SANBOX_API_URL || defaultApiUrl).replace(/\/+$/, "");
+    const org = String(flags.org || process.env.SANBOX_ORG || "").trim();
+    const apiKey = process.env.SANBOX_API_KEY || "";
+    if (!org)
+        throw new Error("SANBOX_ORG or --org is required.");
+    if (!apiKey)
+        throw new Error("SANBOX_API_KEY is required.");
+    return { apiUrl, org, apiKey };
+};

package/dist/dossier.js

@@ -0,0 +1,108 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import fg from "fast-glob";
+import ignore from "ignore";
+import yazl from "yazl";
+const defaultIgnorePatterns = [
+    ".git/**",
+    "**/.git/**",
+    "node_modules/**",
+    "**/node_modules/**",
+    "dist/**",
+    "**/dist/**",
+    "build/**",
+    "**/build/**",
+    "coverage/**",
+    "**/coverage/**",
+    ".next/**",
+    "**/.next/**",
+    ".turbo/**",
+    "**/.turbo/**",
+    ".env",
+    ".env.*",
+    "**/.env",
+    "**/.env.*",
+    "**/*secret*",
+    "**/*Secret*",
+    "**/*token*",
+    "**/*Token*",
+    "**/*credential*",
+    "**/*Credential*",
+    "**/*.pem",
+    "**/*.key",
+    "**/id_rsa",
+    "**/id_ed25519"
+];
+const normalizeInclude = (patterns) => patterns.length === 0 ? ["**/*"] : patterns.map((pattern) => (pattern === "." ? "**/*" : pattern));
+const readSanboxIgnore = async (cwd) => {
+    try {
+        const raw = await fs.readFile(path.join(cwd, ".sanboxignore"), "utf8");
+        return raw.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith("#"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+};
+const zipToBuffer = async (zip) => new Promise((resolve, reject) => {
+    const chunks = [];
+    zip.outputStream.on("data", (chunk) => chunks.push(chunk));
+    zip.outputStream.on("error", reject);
+    zip.outputStream.on("end", () => resolve(Buffer.concat(chunks)));
+    zip.end();
+});
+export const sha256 = (buffer) => crypto.createHash("sha256").update(buffer).digest("hex");
+export const buildTaskDossier = async (input) => {
+    const patterns = normalizeInclude(input.include);
+    const ig = ignore().add([...defaultIgnorePatterns, ...(await readSanboxIgnore(input.cwd))]);
+    const candidates = await fg(patterns, {
+        cwd: input.cwd,
+        dot: true,
+        onlyFiles: true,
+        followSymbolicLinks: false,
+        unique: true
+    });
+    const files = candidates
+        .map((item) => item.replaceAll(path.sep, "/"))
+        .filter((item) => !item.startsWith("../") && !path.isAbsolute(item))
+        .filter((item) => !ig.ignores(item))
+        .sort();
+    const zip = new yazl.ZipFile();
+    const fileMetadata = [];
+    const runbook = [
+        "# Sanbox Task",
+        "",
+        "Follow these instructions exactly.",
+        "",
+        input.task.trim(),
+        "",
+        "Write durable results under `/workspace/output`.",
+        "Use files under `/workspace/dossier/input/repo` as the provided source context."
+    ].join("\n");
+    zip.addBuffer(Buffer.from(runbook, "utf8"), "RUNBOOK.md");
+    for (const rel of files) {
+        const abs = path.join(input.cwd, rel);
+        const stat = await fs.stat(abs);
+        if (!stat.isFile())
+            continue;
+        const content = await fs.readFile(abs);
+        fileMetadata.push({ path: rel, size: stat.size, sha256: sha256(content) });
+        zip.addBuffer(content, `input/repo/${rel}`);
+    }
+    const manifest = {
+        source: "sanbox-cli",
+        cli_version: input.cliVersion,
+        created_at: new Date().toISOString(),
+        task: input.task,
+        files: fileMetadata
+    };
+    zip.addBuffer(Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, "utf8"), "manifest.json");
+    const buffer = await zipToBuffer(zip);
+    return { buffer, sha256: sha256(buffer), files: fileMetadata };
+};
+export const readDossierFile = async (dossierPath) => {
+    const buffer = await fs.readFile(dossierPath);
+    return { buffer, sha256: sha256(buffer), files: [] };
+};

package/dist/mcp.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as z from "zod/v4";
+import { SanboxClient } from "./api.js";
+import { defaultWorkloadId, readConfig } from "./config.js";
+import { createRun, readTasks, runPool, stableBatchId, waitForRun } from "./runs.js";
+import { version } from "./version.js";
+const textAndJson = (summary, structuredContent) => ({
+    content: [{ type: "text", text: `${summary}\n\n${JSON.stringify(structuredContent, null, 2)}` }],
+    structuredContent
+});
+const client = () => new SanboxClient(readConfig());
+const server = new McpServer({
+    name: "sanbox",
+    version
+});
+server.registerTool("create_sandbox_run", {
+    title: "Create Sanbox Run",
+    description: "Create one Sanbox run from a task or existing dossier ZIP.",
+    inputSchema: {
+        task: z.string().optional().describe("Task instructions. Required unless dossier_path is provided."),
+        dossier_path: z.string().optional().describe("Path to an existing dossier ZIP."),
+        include: z.array(z.string()).optional().describe("Repo file globs to include when task is provided."),
+        external_run_id: z.string().optional().describe("Optional idempotency key."),
+        workload_id: z.string().optional().default(defaultWorkloadId),
+        wait: z.boolean().optional().default(false)
+    }
+}, async (args) => {
+    if (!args.task && !args.dossier_path)
+        throw new Error("task or dossier_path is required.");
+    const api = client();
+    let payload = await createRun(api, {
+        cwd: process.cwd(),
+        cliVersion: version,
+        task: args.task,
+        dossierPath: args.dossier_path,
+        include: args.include || [],
+        externalRunId: args.external_run_id,
+        workloadId: args.workload_id || defaultWorkloadId
+    });
+    if (args.wait)
+        payload = await waitForRun(api, payload.run.id);
+    return textAndJson(`Run ${payload.run.id} is ${payload.run.status}.`, payload);
+});
+server.registerTool("create_sandbox_runs", {
+    title: "Create Multiple Sanbox Runs",
+    description: "Create independent Sanbox runs for parallel task delegation.",
+    inputSchema: {
+        tasks: z.array(z.object({
+            task: z.string(),
+            external_run_id: z.string().optional(),
+            include: z.array(z.string()).optional()
+        })).optional().describe("Inline tasks to run."),
+        tasks_path: z.string().optional().describe("Path to a JSON task array."),
+        include: z.array(z.string()).optional().describe("Default repo file globs for generated dossiers."),
+        batch_id: z.string().optional().describe("Optional stable batch id for idempotency."),
+        max_parallel: z.number().int().min(1).max(20).optional().default(5),
+        wait: z.boolean().optional().default(false)
+    }
+}, async (args) => {
+    const tasks = args.tasks_path ? await readTasks(args.tasks_path) : args.tasks;
+    if (!tasks || tasks.length === 0)
+        throw new Error("tasks or tasks_path is required.");
+    const batchId = args.batch_id || (args.tasks_path ? await stableBatchId(args.tasks_path) : `mcp-${Date.now().toString(36)}`);
+    const api = client();
+    const results = await runPool(tasks, args.max_parallel || 5, async (task, index) => {
+        let payload = await createRun(api, {
+            cwd: process.cwd(),
+            cliVersion: version,
+            task: task.task,
+            include: task.include || args.include || [],
+            externalRunId: task.external_run_id || `sanbox-batch-${batchId}-${index + 1}`,
+            workloadId: defaultWorkloadId
+        });
+        if (args.wait)
+            payload = await waitForRun(api, payload.run.id);
+        return payload;
+    });
+    const structured = { batch_id: batchId, runs: results.map((result) => result.run), results };
+    return textAndJson(`Created ${results.length} Sanbox runs.`, structured);
+});
+server.registerTool("get_sandbox_run", {
+    title: "Get Sanbox Run",
+    description: "Fetch a Sanbox run and recent events.",
+    inputSchema: {
+        run_id: z.string()
+    }
+}, async ({ run_id }) => {
+    const payload = await client().getRun(run_id);
+    return textAndJson(`Run ${payload.run.id} is ${payload.run.status}.`, payload);
+});
+server.registerTool("list_sandbox_events", {
+    title: "List Sanbox Events",
+    description: "List events for a Sanbox run.",
+    inputSchema: {
+        run_id: z.string(),
+        after_event_id: z.number().int().min(0).optional().default(0)
+    }
+}, async ({ run_id, after_event_id }) => {
+    const payload = await client().listEvents(run_id, after_event_id || 0);
+    return textAndJson(`Found ${payload.events.length} events.`, payload);
+});
+server.registerTool("cancel_sandbox_run", {
+    title: "Cancel Sanbox Run",
+    description: "Request cancellation for a queued or running Sanbox run.",
+    inputSchema: {
+        run_id: z.string()
+    }
+}, async ({ run_id }) => {
+    const payload = await client().cancelRun(run_id);
+    return textAndJson(`Cancel requested for ${payload.run.id}.`, payload);
+});
+server.registerTool("send_sandbox_message", {
+    title: "Send Sanbox Message",
+    description: "Ask a follow-up question against a retained Sanbox run workspace.",
+    inputSchema: {
+        run_id: z.string(),
+        message: z.string()
+    }
+}, async ({ run_id, message }) => {
+    const payload = await client().sendMessage(run_id, message);
+    return textAndJson(`Message sent to ${payload.run.id}.`, payload);
+});
+const main = async () => {
+    await server.connect(new StdioServerTransport());
+};
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/output.js

@@ -0,0 +1,10 @@
+export const printJson = (value) => {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+};
+export const summarizeRun = (payload) => {
+    const { run } = payload;
+    return `${run.id} ${run.status}${run.exit_code === null ? "" : ` exit=${run.exit_code}`}${run.error ? ` error=${run.error}` : ""}`;
+};
+export const printRun = (payload) => {
+    process.stdout.write(`${summarizeRun(payload)}\n`);
+};

package/dist/runs.js

@@ -0,0 +1,88 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { defaultWorkloadId } from "./config.js";
+import { buildTaskDossier, readDossierFile } from "./dossier.js";
+const terminalStatuses = new Set(["completed", "failed", "canceled", "expired"]);
+const inlineLimitBytes = 8 * 1024 * 1024;
+export const isTerminalRun = (run) => terminalStatuses.has(run.status);
+export const waitForRun = async (client, runId, options = {}) => {
+    const pollIntervalMs = options.pollIntervalMs ?? 2000;
+    const deadline = Date.now() + (options.timeoutSeconds ?? 1800) * 1000;
+    let payload = await client.getRun(runId);
+    while (!isTerminalRun(payload.run)) {
+        if (Date.now() > deadline)
+            throw new Error(`Timed out waiting for run ${runId}.`);
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        payload = await client.getRun(runId);
+    }
+    return payload;
+};
+export const createRun = async (client, options) => {
+    const dossier = options.dossierPath
+        ? await readDossierFile(path.resolve(options.cwd, options.dossierPath))
+        : await buildTaskDossier({
+            cwd: options.cwd,
+            task: options.task || "",
+            include: options.include,
+            cliVersion: options.cliVersion
+        });
+    if (dossier.buffer.byteLength > inlineLimitBytes) {
+        throw new Error(`Dossier is ${dossier.buffer.byteLength} bytes; inline dossier limit is ${inlineLimitBytes} bytes.`);
+    }
+    const manifest = {
+        dossier: {
+            inline_base64: dossier.buffer.toString("base64"),
+            sha256: dossier.sha256
+        },
+        sanbox_cli: {
+            files: dossier.files,
+            source: options.dossierPath ? "dossier_file" : "generated_task"
+        }
+    };
+    return client.createRun({
+        external_run_id: options.externalRunId,
+        workload_id: options.workloadId || defaultWorkloadId,
+        manifest,
+        retention_ttl_seconds: options.retentionTtlSeconds
+    });
+};
+export const readTasks = async (tasksPath) => {
+    const raw = await fs.readFile(tasksPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed))
+        throw new Error("tasks file must be a JSON array.");
+    return parsed.map((item, index) => {
+        if (typeof item === "string")
+            return { task: item };
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new Error(`tasks[${index}] must be a string or object.`);
+        }
+        const record = item;
+        const task = String(record.task || "").trim();
+        if (!task)
+            throw new Error(`tasks[${index}].task is required.`);
+        return {
+            task,
+            external_run_id: record.external_run_id ? String(record.external_run_id) : undefined,
+            include: Array.isArray(record.include) ? record.include.map(String) : undefined
+        };
+    });
+};
+export const stableBatchId = async (tasksPath) => {
+    const abs = path.resolve(tasksPath);
+    const raw = await fs.readFile(abs);
+    return crypto.createHash("sha256").update(abs).update("\0").update(raw).digest("hex").slice(0, 16);
+};
+export const runPool = async (items, concurrency, worker) => {
+    const results = new Array(items.length);
+    let cursor = 0;
+    const count = Math.max(1, Math.min(items.length || 1, concurrency));
+    await Promise.all(Array.from({ length: count }, async () => {
+        while (cursor < items.length) {
+            const index = cursor++;
+            results[index] = await worker(items[index], index);
+        }
+    }));
+    return results;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/version.js

@@ -0,0 +1 @@
+export const version = "0.0.1";

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@sanlabs/sanbox-cli",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "sanbox": "dist/cli.js",
+    "sanbox-mcp": "dist/mcp.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.21.0",
+    "fast-glob": "^3.3.3",
+    "ignore": "^7.0.5",
+    "yazl": "^3.3.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@types/yazl": "^3.3.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3"
+  }
+}