@sanlabs/sanbox-cli 0.0.3 → 0.0.5

package/README.md

@@ -1,136 +1,129 @@
 # 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.
+Sanbox packages a task and selected inputs, starts an isolated runner, streams events, and keeps the sandbox and outputs indefinitely.
+
+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
+latest_cli_version="$(npm view @sanlabs/sanbox-cli version)"
+installed_cli_version="$(sanbox --version)"
+test "$installed_cli_version" = "$latest_cli_version"
 ```
 
-## Configure
+Always use the latest published CLI. CLI 0.0.5 adds organization discovery from the API key,
+Hermes-aware template metadata, permanent paused sandboxes, and same-sandbox 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>
+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`.
+The CLI derives the organization automatically from `SANBOX_API_KEY`; use an organization-scoped
+key that has access to exactly one organization.
 
-`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 a provider, model, or template.
+For waited task runs, choose a template with `runnable: true`, `template_type: "runner"`, and
+`runner_config.harness: "opencode"`. Hermes service templates are always-on.
 
-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.
-
-## Run a Task
+Repeat `--input` for files, directories, or globs. The CLI excludes common secrets and applies `.sanboxignore`. `--include` is a deprecated compatibility alias.
 
-```bash
-sanbox run "Review this repo and write output/report.md" --template <template-id> --include "src/**" --watch
-```
+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.
 
-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.
+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.
 
-`--wait` remains available when only the final run result is needed.
+Completed runs pause into a durable Firecracker snapshot. `sanbox runs message <run-id> --message "..."`
+resumes the same writable sandbox and OpenCode session, then pauses it again. There is no retention
+TTL; paused sandboxes and their artifacts remain available until explicitly deleted.
 
-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`.
+Check `sanbox runs get <run-id> --json` before a follow-up and require `sandbox_state: "paused"` with
+a positive `snapshot_generation`. Do not submit concurrent follow-ups to one run.
 
 ## 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

@@ -1,3 +1,4 @@
+import { CliError } from "./errors.js";
 const errorRecord = (body) => {
     if (!body || typeof body !== "object" || Array.isArray(body))
         return null;
@@ -38,6 +39,9 @@ export class SanboxApiError extends Error {
 }
 export class SanboxClient {
     config;
+    mePromise = null;
+    organizationPromise = null;
+    organizationSlug = null;
     constructor(config) {
         this.config = config;
     }
@@ -58,17 +62,83 @@ 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");
+        this.mePromise ||= this.request("/v1/me");
+        return this.mePromise;
+    }
+    organization() {
+        this.organizationPromise ||= this.resolveOrganization();
+        return this.organizationPromise;
+    }
+    resolvedOrganizationSlug() {
+        return this.organizationSlug;
+    }
+    async resolveOrganization() {
+        const me = await this.me();
+        const organizations = Array.isArray(me.organizations)
+            ? me.organizations.filter((item) => Boolean(item)
+                && typeof item === "object"
+                && !Array.isArray(item)
+                && typeof item.id === "string"
+                && typeof item.slug === "string"
+                && Boolean(String(item.slug).trim()))
+            : [];
+        if (organizations.length === 0) {
+            throw new CliError("organization_not_found", "The API key is not associated with an organization.");
+        }
+        if (organizations.length > 1) {
+            throw new CliError("organization_ambiguous", "The API key can access multiple organizations. Use an organization-scoped API key.");
+        }
+        this.organizationSlug = organizations[0].slug;
+        return organizations[0];
+    }
+    async orgPath(path) {
+        const organization = await this.organization();
+        return `/v1/orgs/${encodeURIComponent(organization.slug)}${path}`;
     }
-    createRun(body) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs`, {
+    async listRuns(limit = 50) {
+        return this.request(`${await this.orgPath("/runs")}?limit=${limit}`);
+    }
+    async createRun(body) {
+        return this.request(await this.orgPath("/runs"), {
             method: "POST",
             body: JSON.stringify(body)
         });
     }
-    listModelProviders() {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/model-providers`);
+    async uploadInputCollection(input) {
+        return this.request(await this.orgPath("/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
+        });
+    }
+    async listModelProviders() {
+        return this.request(await this.orgPath("/model-providers"));
     }
     async getModelProvider(providerId) {
         const payload = await this.listModelProviders();
@@ -77,40 +147,49 @@ export class SanboxClient {
             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`);
+    async listProviderModels(providerId) {
+        return this.request(await this.orgPath(`/model-providers/${encodeURIComponent(providerId)}/models`));
     }
-    listTemplates() {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/templates`);
+    async listTemplates() {
+        return this.request(await this.orgPath("/templates"));
     }
-    getTemplate(templateId) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/templates/${encodeURIComponent(templateId)}`);
+    async getTemplate(templateId) {
+        return this.request(await this.orgPath(`/templates/${encodeURIComponent(templateId)}`));
     }
-    validateTemplate(templateId) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/templates/${encodeURIComponent(templateId)}/validate`);
+    async validateTemplate(templateId) {
+        return this.request(await this.orgPath(`/templates/${encodeURIComponent(templateId)}/validate`));
     }
-    createTemplate(body) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/templates`, {
+    async createTemplate(body) {
+        return this.request(await this.orgPath("/templates"), {
             method: "POST",
             body: JSON.stringify(body)
         });
     }
-    getRun(runId, signal) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}`, { signal });
+    async getRun(runId, signal) {
+        return this.request(await this.orgPath(`/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 });
+    async listEvents(runId, afterEventId = 0, limit = 200, signal) {
+        return this.request(`${await this.orgPath(`/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`, {
+    async cancelRun(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/cancel`), {
             method: "POST",
             body: "{}"
         });
     }
-    sendMessage(runId, message, payload = {}) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/messages`, {
+    async sendMessage(runId, message, payload = {}) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/messages`), {
             method: "POST",
             body: JSON.stringify({ message, payload })
         });
     }
+    async listMessages(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/messages`));
+    }
+    async listArtifacts(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/artifacts`));
+    }
+    async downloadArtifact(runId, artifactPath) {
+        return this.rawRequest(`${await this.orgPath(`/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", "telegram-allowed-user"]);
+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;
+};