@sanlabs/sanbox-cli 0.0.3 → 0.0.4

package/README.md

@@ -1,136 +1,115 @@
 # Sanbox CLI
 
-Run Sanbox agent tasks from a terminal, CI job, or coding agent.
+Run isolated Sanbox agent tasks from a terminal, CI job, or autonomous coding agent.
 
-Sanbox packages a task and selected inputs, starts an isolated runner, streams events, and keeps the outputs in a retained workspace.
+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
-npm install -g @sanlabs/sanbox-cli
+npm install -g @sanlabs/sanbox-cli@latest
+sanbox --version
 ```
 
-## Configure
+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.
 
-Create an API key in the Sanbox console, then set:
+## Configure
 
 ```bash
 export SANBOX_API_URL=https://console.sanbox.cloud
-export SANBOX_ORG=<org-slug>
 export SANBOX_API_KEY=sbx_live_...
-export SANBOX_TEMPLATE=<template-id>
+sanbox orgs list --json
+export SANBOX_ORG=<returned-org-slug>
+export SANBOX_TEMPLATE=<template-id-or-slug>
 ```
 
-`SANBOX_API_URL` defaults to `https://console.sanbox.cloud`. Set it only for self-hosted or local deployments.
-`SANBOX_TEMPLATE` is optional when every run uses `--template` or `.sanbox/config.json` contains an explicit `default_template`.
+`SANBOX_API_URL` is optional for the hosted service. `SANBOX_TEMPLATE` can instead come from `--template` or `.sanbox/config.json` `default_template`.
 
-`SANBOX_API_KEY` authenticates to Sanbox. Model-provider credentials are separate, organization-scoped, and configured by an admin in the console. Do not pass provider keys to the CLI.
+An org admin configures provider credentials and templates in the console. Do not pass provider keys to the CLI or a runner.
 
-## Check Access
+## Check Readiness
 
 ```bash
-sanbox doctor
-sanbox auth check
+sanbox auth check --json
 sanbox context --json
+sanbox templates list --json
+sanbox templates validate "$SANBOX_TEMPLATE" --json
+sanbox doctor --json
 ```
 
-## Choose A Model Provider And Template
-
-List model providers configured for the selected organization, then list the exact models exposed by one provider:
-
-```bash
-sanbox model-providers list --json
-sanbox model-providers get <provider-id> --json
-sanbox model-providers models <provider-id> --json
-```
-
-Model ids are scoped to their provider. If two providers expose the same model id, they remain separate choices.
+Model IDs are provider-scoped. The CLI never guesses or silently substitutes an organization, provider, model, or template.
 
-List and inspect templates:
+## Run Idempotently
 
 ```bash
-sanbox templates list --json
-sanbox templates get <template-id> --json
-sanbox templates validate <template-id> --json
-```
-
-Organization admins can create a template with an exact provider/model pair:
+sanbox run "Review this repo and write output/report.md" \
+  --input src/ \
+  --dry-run \
+  --json
 
-```bash
-sanbox templates create \
-  --name "Code review" \
-  --model-provider <provider-id> \
-  --model <exact-model-id> \
+sanbox run "Review this repo and write output/report.md" \
+  --template "$SANBOX_TEMPLATE" \
+  --external-run-id "<stable-project-task-id>" \
+  --input src/ \
+  --wait \
   --json
 ```
 
-The CLI does not recommend or automatically select a provider or model.
+Repeat `--input` for files, directories, or globs. The CLI excludes common secrets and applies `.sanboxignore`. `--include` is a deprecated compatibility alias.
 
-## Run a Task
+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.
 
-```bash
-sanbox run "Review this repo and write output/report.md" --template <template-id> --include "src/**" --watch
-```
-
-Use repeatable `--include` flags to choose what is sent to the runner:
+## Inspect And Recover
 
 ```bash
-sanbox run "Fill the report template from these notes" \
-  --template <template-id> \
-  --include "templates/report.docx" \
-  --include "docs/source/**" \
-  --watch
+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
 ```
 
-Sanbox excludes `.git`, `node_modules`, build output, `.env` files, private keys, and common secret-like filenames by default. Add `.sanboxignore` for project-specific excludes.
-
-## Watch Agent Activity
+## Retrieve Outputs
 
-Create a run and stream its activity until completion:
+Tasks should write durable deliverables under `/workspace/output`.
 
 ```bash
-sanbox run "Fix the authentication tests" --template <template-id> --include "src/**" --watch
+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
 ```
 
-Reattach to an existing run:
+Downloads are path-safe and return their byte counts and SHA-256 digests. Existing files are preserved unless `--overwrite` is explicit.
 
-```bash
-sanbox runs watch <run-id>
-```
-
-Use JSONL for scripts and agents:
+## Continue A Run
 
 ```bash
-sanbox runs watch <run-id> --jsonl
+sanbox runs messages <run-id> --json
+sanbox runs message <run-id> "Summarize the retained output" --wait --json
 ```
 
-`--view logs` shows only stdout/stderr events, while `--view compact` hides them. Ctrl-C detaches without canceling the run. Use `--cancel-on-interrupt` only when the watcher and run should share a lifetime, such as a CI job.
-
-`--wait` remains available when only the final run result is needed.
-
-OpenCode runner images normalize session, turn, tool completion/failure, file-change, assistant-message, usage, and error activity. The unmodified provider stream is retained separately at `/workspace/logs/opencode.jsonl`; provider stderr is retained at `/workspace/logs/opencode.stderr.log`.
+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
 
-```bash
-sanbox batch --tasks tasks.json --template <template-id> --include "src/**" --max-parallel 5 --wait --json
+```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/"] }
+]
 ```
 
-## Inspect a Run Bundle
-
 ```bash
-sanbox bundle preview --include "app/**"
-sanbox bundle create "Review this repo" --include "app/**" --out run.zip
-sanbox bundle inspect run.zip
+sanbox batch --tasks tasks.json --template "$SANBOX_TEMPLATE" --max-parallel 5 --wait --json
 ```
 
-## Use From Agents
-
-Use Sanbox for independent, long-running, risky, or parallelizable work. Tell the runner to write durable results under `/workspace/output`.
+Batch fan-out is client-side. Keep the CLI process alive until all tasks are submitted.
 
-Use the CLI directly from coding agents that can run shell commands, including Codex and Claude Code.
+## Machine Output
 
-## Links
+Use `--json` for request/response commands and `--jsonl` for streams. Envelopes have `schema_version`, `ok`, `command`, `context`, `data` or `error`, and `next_actions`.
 
-- Console: https://console.sanbox.cloud
-- Agent instructions: https://console.sanbox.cloud/agent.md
+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/api.js

@@ -58,15 +58,53 @@ export class SanboxClient {
         }
         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)
         });
     }
+    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`);
     }
@@ -113,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;
+};