@sanlabs/sanbox-cli 0.0.1 → 0.0.4

package/README.md

@@ -1,15 +1,115 @@
 # Sanbox CLI
 
-Agent-facing CLI and local MCP server for creating Sanbox runs.
+Run isolated Sanbox agent tasks from a terminal, CI job, or autonomous coding agent.
+
+The full machine operating protocol is available at https://console.sanbox.cloud/agent.md and in [`web/public/agent.md`](../web/public/agent.md).
+
+## Install
 
 ```bash
-export SANBOX_API_URL=http://167.233.236.51
-export SANBOX_ORG=rheinfall-bank
+npm install -g @sanlabs/sanbox-cli@latest
+sanbox --version
+```
+
+CLI 0.0.4 adds strict argument validation, stable JSON envelopes, existing-resource discovery, resumable watches, verified artifact downloads, and correlated post-run follow-ups.
+
+## Configure
+
+```bash
+export SANBOX_API_URL=https://console.sanbox.cloud
 export SANBOX_API_KEY=sbx_live_...
+sanbox orgs list --json
+export SANBOX_ORG=<returned-org-slug>
+export SANBOX_TEMPLATE=<template-id-or-slug>
+```
+
+`SANBOX_API_URL` is optional for the hosted service. `SANBOX_TEMPLATE` can instead come from `--template` or `.sanbox/config.json` `default_template`.
+
+An org admin configures provider credentials and templates in the console. Do not pass provider keys to the CLI or a runner.
+
+## Check Readiness
+
+```bash
+sanbox auth check --json
+sanbox context --json
+sanbox templates list --json
+sanbox templates validate "$SANBOX_TEMPLATE" --json
+sanbox doctor --json
+```
+
+Model IDs are provider-scoped. The CLI never guesses or silently substitutes an organization, provider, model, or template.
+
+## Run Idempotently
+
+```bash
+sanbox run "Review this repo and write output/report.md" \
+  --input src/ \
+  --dry-run \
+  --json
+
+sanbox run "Review this repo and write output/report.md" \
+  --template "$SANBOX_TEMPLATE" \
+  --external-run-id "<stable-project-task-id>" \
+  --input src/ \
+  --wait \
+  --json
+```
+
+Repeat `--input` for files, directories, or globs. The CLI excludes common secrets and applies `.sanboxignore`. `--include` is a deprecated compatibility alias.
+
+Reuse the same external ID when retrying an ambiguous submission. To stream activity, replace `--wait --json` with `--jsonl`. Ctrl-C detaches without canceling unless `--cancel-on-interrupt` is supplied.
 
-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
+## Inspect And Recover
+
+```bash
+sanbox runs list --limit 50 --json
+sanbox runs get <run-id> --json
+sanbox runs events <run-id> --after-event-id <cursor> --json
+sanbox runs watch <run-id> --after-event-id <cursor> --jsonl
+```
+
+## Retrieve Outputs
+
+Tasks should write durable deliverables under `/workspace/output`.
+
+```bash
+sanbox runs artifacts <run-id> --json
+sanbox runs download <run-id> --output .sanbox/output/<run-id> --json
+sanbox runs download <run-id> \
+  --output .sanbox/output/<run-id> \
+  --artifact report.md \
+  --overwrite \
+  --json
+```
+
+Downloads are path-safe and return their byte counts and SHA-256 digests. Existing files are preserved unless `--overwrite` is explicit.
+
+## Continue A Run
+
+```bash
+sanbox runs messages <run-id> --json
+sanbox runs message <run-id> "Summarize the retained output" --wait --json
+```
+
+The JSON response includes the user `message`, submitted `chat_job`, matching terminal `followup_event`, and conversation messages. The waiter matches `payload.chat_job_id`, so another concurrent follow-up cannot complete the wrong command.
+
+## Batch Work
+
+```json
+[
+  { "task": "Review API behavior and write output/api.md", "external_run_id": "review-api", "input": ["app/"] },
+  { "task": "Review CLI behavior and write output/cli.md", "external_run_id": "review-cli", "input": ["cli/"] }
+]
 ```
 
-The package also exposes `sanbox-mcp`, a local stdio MCP server for tools such as Codex, Claude Code, Cursor, and Copilot.
+```bash
+sanbox batch --tasks tasks.json --template "$SANBOX_TEMPLATE" --max-parallel 5 --wait --json
+```
+
+Batch fan-out is client-side. Keep the CLI process alive until all tasks are submitted.
+
+## Machine Output
+
+Use `--json` for request/response commands and `--jsonl` for streams. Envelopes have `schema_version`, `ok`, `command`, `context`, `data` or `error`, and `next_actions`.
+
+Exit codes are `0` for command success, `1` for local/API failure, `2` for readiness or waited remote failure, and `130` for a detached watcher.

package/dist/activity.js

@@ -0,0 +1,72 @@
+export const parseActivityView = (value) => {
+    const normalized = value.trim() || "activity";
+    if (normalized === "activity" || normalized === "logs" || normalized === "compact")
+        return normalized;
+    throw new Error("--view must be one of: activity, logs, compact.");
+};
+export const shouldRenderEvent = (event, view) => {
+    const isLog = event.kind === "log.stdout" || event.kind === "log.stderr";
+    if (view === "logs")
+        return isLog;
+    if (view === "compact")
+        return !isLog;
+    return true;
+};
+const elapsed = (createdAt, occurredAt) => {
+    const start = Date.parse(createdAt);
+    const end = Date.parse(occurredAt);
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        return "--:--";
+    const totalSeconds = Math.max(0, Math.floor((end - start) / 1000));
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    return hours > 0
+        ? `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`
+        : `${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+};
+const oneLine = (value) => value
+    .replace(/[\r\n\t]+/g, " ")
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "")
+    .trim();
+export const formatActivityLine = (event, runCreatedAt) => {
+    const summary = oneLine(event.message);
+    const bounded = summary.length > 500 ? `${summary.slice(0, 497)}...` : summary;
+    return `${elapsed(runCreatedAt, event.created_at).padStart(8)}  ${event.kind.padEnd(22)} ${bounded}`.trimEnd();
+};
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const safeEventData = (value) => {
+    if (Array.isArray(value))
+        return value.map(safeEventData);
+    if (!isRecord(value))
+        return value;
+    const output = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (key === "workspace_id" || key === "workspace_path" || key === "host_path")
+            continue;
+        output[key] = safeEventData(item);
+    }
+    return output;
+};
+export const activityEnvelope = (event) => {
+    const normalized = event.payload.schema_version === 1 && isRecord(event.payload.source);
+    const occurredAt = normalized && typeof event.payload.occurred_at === "string"
+        ? event.payload.occurred_at
+        : event.created_at;
+    return {
+        schema_version: 1,
+        scope: "run",
+        run_id: event.run_id,
+        cursor: String(event.id),
+        kind: event.kind,
+        level: event.level,
+        summary: event.message,
+        source: normalized ? event.payload.source : { plane: "control_plane", trust: "control_plane" },
+        sequence: normalized && typeof event.payload.sequence === "number" ? event.payload.sequence : null,
+        correlation: normalized && isRecord(event.payload.correlation) ? event.payload.correlation : {},
+        data: safeEventData(normalized ? event.payload.data : event.payload),
+        occurred_at: occurredAt,
+        observed_at: event.created_at
+    };
+};
+export const formatActivityJsonl = (event) => JSON.stringify(activityEnvelope(event));

package/dist/api.js

@@ -1,10 +1,39 @@
+const errorRecord = (body) => {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return null;
+    return body;
+};
+const apiErrorCode = (body) => {
+    const record = errorRecord(body);
+    if (!record)
+        return "api_error";
+    if (typeof record.code === "string" && record.code)
+        return record.code;
+    const nested = errorRecord(record.error);
+    return typeof nested?.code === "string" && nested.code ? nested.code : "api_error";
+};
+const apiErrorMessage = (body, fallback) => {
+    const record = errorRecord(body);
+    if (!record)
+        return fallback;
+    if (typeof record.error === "string" && record.error)
+        return record.error;
+    const nested = errorRecord(record.error);
+    if (typeof nested?.message === "string" && nested.message)
+        return nested.message;
+    if (typeof record.message === "string" && record.message)
+        return record.message;
+    return fallback;
+};
 export class SanboxApiError extends Error {
     status;
     body;
+    code;
     constructor(message, status, body) {
         super(message);
         this.status = status;
         this.body = body;
+        this.code = apiErrorCode(body);
     }
 }
 export class SanboxClient {
@@ -24,25 +53,91 @@ export class SanboxClient {
         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;
+            const message = apiErrorMessage(body, res.statusText);
             throw new SanboxApiError(message, res.status, body);
         }
         return body;
     }
+    async rawRequest(path, init = {}) {
+        const res = await fetch(`${this.config.apiUrl}${path}`, {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${this.config.apiKey}`,
+                ...(init.headers || {})
+            }
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            let body = {};
+            try {
+                body = text ? JSON.parse(text) : {};
+            }
+            catch {
+                body = { error: text || res.statusText };
+            }
+            throw new SanboxApiError(apiErrorMessage(body, res.statusText), res.status, body);
+        }
+        return res;
+    }
     me() {
         return this.request("/v1/me");
     }
+    listOrganizations() {
+        return this.request("/v1/orgs");
+    }
+    listRuns(limit = 50) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs?limit=${limit}`);
+    }
     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)}`);
+    uploadInputCollection(input) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/input-collections`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/vnd.sanbox.input+zip",
+                "X-Sanbox-Content-SHA256": input.sha256,
+                "X-Sanbox-File-Count": String(input.fileCount)
+            },
+            body: Uint8Array.from(input.buffer).buffer
+        });
+    }
+    listModelProviders() {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/model-providers`);
+    }
+    async getModelProvider(providerId) {
+        const payload = await this.listModelProviders();
+        const provider = payload.providers.find((item) => (item.provider_id || item.id) === providerId);
+        if (!provider)
+            throw new SanboxApiError(`Model provider ${providerId} was not found.`, 404, { code: "model_provider_not_found" });
+        return { provider };
+    }
+    listProviderModels(providerId) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/model-providers/${encodeURIComponent(providerId)}/models`);
     }
-    listEvents(runId, afterEventId = 0) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/events?after_event_id=${afterEventId}`);
+    listTemplates() {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/templates`);
+    }
+    getTemplate(templateId) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/templates/${encodeURIComponent(templateId)}`);
+    }
+    validateTemplate(templateId) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/templates/${encodeURIComponent(templateId)}/validate`);
+    }
+    createTemplate(body) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/templates`, {
+            method: "POST",
+            body: JSON.stringify(body)
+        });
+    }
+    getRun(runId, signal) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}`, { signal });
+    }
+    listEvents(runId, afterEventId = 0, limit = 200, signal) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/events?after_event_id=${afterEventId}&limit=${limit}`, { signal });
     }
     cancelRun(runId) {
         return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/cancel`, {
@@ -56,4 +151,13 @@ export class SanboxClient {
             body: JSON.stringify({ message, payload })
         });
     }
+    listMessages(runId) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/messages`);
+    }
+    listArtifacts(runId) {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/artifacts`);
+    }
+    downloadArtifact(runId, artifactPath) {
+        return this.rawRequest(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/artifacts?path=${encodeURIComponent(artifactPath)}`);
+    }
 }

package/dist/args.js

@@ -1,4 +1,19 @@
-const multiFlags = new Set(["include"]);
+const multiFlags = new Set(["input", "include", "artifact"]);
+export const booleanFlags = new Set([
+    "help",
+    "version",
+    "json",
+    "web-access",
+    "dry-run",
+    "wait",
+    "watch",
+    "jsonl",
+    "cancel-on-interrupt",
+    "verbose",
+    "force",
+    "write",
+    "overwrite"
+]);
 export const parseArgs = (argv) => {
     const command = [];
     const flags = {};
@@ -12,10 +27,15 @@ export const parseArgs = (argv) => {
         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);
+        const value = inlineValue ?? (booleanFlags.has(key)
+            ? true
+            : 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)];
+            const serialized = value === true ? "" : String(value);
+            flags[key] = Array.isArray(existing) ? [...existing, serialized] : [serialized];
         }
         else {
             flags[key] = value;
@@ -31,10 +51,6 @@ export const flagString = (flags, key, fallback = "") => {
         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))

package/dist/artifacts.js

@@ -0,0 +1,124 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+export class ArtifactExistsError extends Error {
+    artifactPath;
+    destination;
+    constructor(artifactPath, destination) {
+        super(`Refusing to replace existing artifact file ${destination}. Use --overwrite or a different --output directory.`);
+        this.artifactPath = artifactPath;
+        this.destination = destination;
+    }
+}
+export const artifactDestination = (outputDirectory, artifactPath) => {
+    if (!artifactPath ||
+        artifactPath.startsWith("/") ||
+        artifactPath.includes("\\") ||
+        /[\u0000-\u001f\u007f]/.test(artifactPath) ||
+        artifactPath.split("/").some((component) => !component || component === "." || component === "..")) {
+        throw new Error(`Unsafe artifact path returned by the server: ${JSON.stringify(artifactPath)}.`);
+    }
+    const root = path.resolve(outputDirectory);
+    const destination = path.resolve(root, ...artifactPath.split("/"));
+    if (!destination.startsWith(`${root}${path.sep}`)) {
+        throw new Error(`Artifact path escapes the output directory: ${JSON.stringify(artifactPath)}.`);
+    }
+    return destination;
+};
+const ensureArtifactParent = async (root, destination) => {
+    const parent = path.dirname(destination);
+    const relative = path.relative(root, parent);
+    let current = root;
+    for (const component of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, component);
+        let info;
+        try {
+            info = await fs.lstat(current);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            await fs.mkdir(current);
+            info = await fs.lstat(current);
+        }
+        if (info.isSymbolicLink() || !info.isDirectory()) {
+            throw new Error(`Artifact parent is not a safe directory: ${current}.`);
+        }
+    }
+};
+export const downloadArtifacts = async (client, runId, artifacts, outputDirectory, overwrite) => {
+    const root = path.resolve(outputDirectory);
+    await fs.mkdir(root, { recursive: true });
+    const downloads = [];
+    for (const artifact of artifacts) {
+        const destination = artifactDestination(root, artifact.path);
+        await ensureArtifactParent(root, destination);
+        if (!overwrite) {
+            try {
+                await fs.lstat(destination);
+                throw new ArtifactExistsError(artifact.path, destination);
+            }
+            catch (error) {
+                if (error instanceof ArtifactExistsError)
+                    throw error;
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        const temporary = path.join(path.dirname(destination), `.${path.basename(destination)}.${randomUUID()}.part`);
+        const response = await client.downloadArtifact(runId, artifact.path);
+        if (!response.body)
+            throw new Error(`Artifact ${artifact.path} returned an empty response body.`);
+        const digest = createHash("sha256");
+        let sizeBytes = 0;
+        const verifier = new Transform({
+            transform(chunk, _encoding, callback) {
+                sizeBytes += chunk.byteLength;
+                digest.update(chunk);
+                callback(null, chunk);
+            }
+        });
+        try {
+            await pipeline(Readable.fromWeb(response.body), verifier, createWriteStream(temporary, { flags: "wx", mode: 0o600 }));
+            const expectedLength = response.headers.get("content-length");
+            if (expectedLength && Number(expectedLength) !== sizeBytes) {
+                throw new Error(`Artifact ${artifact.path} length mismatch: expected ${expectedLength}, received ${sizeBytes}.`);
+            }
+            if (artifact.size_bytes !== sizeBytes) {
+                throw new Error(`Artifact ${artifact.path} length mismatch: listed ${artifact.size_bytes}, received ${sizeBytes}.`);
+            }
+            const sha256 = digest.digest("hex");
+            const expectedDigest = response.headers.get("x-content-sha256");
+            if (!expectedDigest || !/^[a-f0-9]{64}$/i.test(expectedDigest)) {
+                throw new Error(`Artifact ${artifact.path} response is missing a valid SHA-256 digest.`);
+            }
+            if (expectedDigest.toLowerCase() !== sha256) {
+                throw new Error(`Artifact ${artifact.path} SHA-256 mismatch.`);
+            }
+            if (overwrite) {
+                await fs.rename(temporary, destination);
+            }
+            else {
+                await fs.link(temporary, destination);
+                await fs.rm(temporary);
+            }
+            downloads.push({
+                path: artifact.path,
+                local_path: destination,
+                size_bytes: sizeBytes,
+                sha256
+            });
+        }
+        catch (error) {
+            await fs.rm(temporary, { force: true }).catch(() => { });
+            if (error.code === "EEXIST") {
+                throw new ArtifactExistsError(artifact.path, destination);
+            }
+            throw error;
+        }
+    }
+    return downloads;
+};