@sanlabs/sanbox-cli 0.0.1 → 0.0.3

package/README.md

@@ -1,15 +1,136 @@
 # Sanbox CLI
 
-Agent-facing CLI and local MCP server for creating Sanbox runs.
+Run Sanbox agent tasks from a terminal, CI job, or coding agent.
+
+Sanbox packages a task and selected inputs, starts an isolated runner, streams events, and keeps the outputs in a retained workspace.
+
+## Install
+
+```bash
+npm install -g @sanlabs/sanbox-cli
+```
+
+## Configure
+
+Create an API key in the Sanbox console, then set:
 
 ```bash
-export SANBOX_API_URL=http://167.233.236.51
-export SANBOX_ORG=rheinfall-bank
+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_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_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.
+
+## Check Access
+
+```bash
+sanbox doctor
 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
+sanbox context --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.
+
+List and inspect templates:
+
+```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:
+
+```bash
+sanbox templates create \
+  --name "Code review" \
+  --model-provider <provider-id> \
+  --model <exact-model-id> \
+  --json
+```
+
+The CLI does not recommend or automatically select a provider or model.
+
+## Run a Task
+
+```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:
+
+```bash
+sanbox run "Fill the report template from these notes" \
+  --template <template-id> \
+  --include "templates/report.docx" \
+  --include "docs/source/**" \
+  --watch
+```
+
+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
+
+Create a run and stream its activity until completion:
+
+```bash
+sanbox run "Fix the authentication tests" --template <template-id> --include "src/**" --watch
+```
+
+Reattach to an existing run:
+
+```bash
+sanbox runs watch <run-id>
+```
+
+Use JSONL for scripts and agents:
+
+```bash
+sanbox runs watch <run-id> --jsonl
+```
+
+`--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`.
+
+## Batch Work
+
+```bash
+sanbox batch --tasks tasks.json --template <template-id> --include "src/**" --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.
+## 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
+```
+
+## Use From Agents
+
+Use Sanbox for independent, long-running, risky, or parallelizable work. Tell the runner to write durable results under `/workspace/output`.
+
+Use the CLI directly from coding agents that can run shell commands, including Codex and Claude Code.
+
+## Links
+
+- Console: https://console.sanbox.cloud
+- Agent instructions: https://console.sanbox.cloud/agent.md

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,7 +53,7 @@ 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;
@@ -38,11 +67,39 @@ export class SanboxClient {
             body: JSON.stringify(body)
         });
     }
-    getRun(runId) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}`);
+    listModelProviders() {
+        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/model-providers`);
     }
-    listEvents(runId, afterEventId = 0) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/events?after_event_id=${afterEventId}`);
+    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`);
+    }
+    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`, {