@sanlabs/sanbox-cli 0.0.4 → 0.0.5

package/README.md

@@ -2,28 +2,33 @@
 
 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 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@latest
-sanbox --version
+latest_cli_version="$(npm view @sanlabs/sanbox-cli version)"
+installed_cli_version="$(sanbox --version)"
+test "$installed_cli_version" = "$latest_cli_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.
+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.
 
 ## 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`.
+The CLI derives the organization automatically from `SANBOX_API_KEY`; use an organization-scoped
+key that has access to exactly one organization.
 
 An org admin configures provider credentials and templates in the console. Do not pass provider keys to the CLI or a runner.
 
@@ -37,7 +42,9 @@ 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.
+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.
 
 ## Run Idempotently
 
@@ -93,6 +100,13 @@ 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.
 
+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.
+
+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
 
 ```json

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;
     }
@@ -80,22 +84,50 @@ export class SanboxClient {
         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];
     }
-    listOrganizations() {
-        return this.request("/v1/orgs");
+    async orgPath(path) {
+        const organization = await this.organization();
+        return `/v1/orgs/${encodeURIComponent(organization.slug)}${path}`;
     }
-    listRuns(limit = 50) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs?limit=${limit}`);
+    async listRuns(limit = 50) {
+        return this.request(`${await this.orgPath("/runs")}?limit=${limit}`);
     }
-    createRun(body) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs`, {
+    async createRun(body) {
+        return this.request(await this.orgPath("/runs"), {
             method: "POST",
             body: JSON.stringify(body)
         });
     }
-    uploadInputCollection(input) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/input-collections`, {
+    async uploadInputCollection(input) {
+        return this.request(await this.orgPath("/input-collections"), {
             method: "POST",
             headers: {
                 "Content-Type": "application/vnd.sanbox.input+zip",
@@ -105,8 +137,8 @@ export class SanboxClient {
             body: Uint8Array.from(input.buffer).buffer
         });
     }
-    listModelProviders() {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/model-providers`);
+    async listModelProviders() {
+        return this.request(await this.orgPath("/model-providers"));
     }
     async getModelProvider(providerId) {
         const payload = await this.listModelProviders();
@@ -115,49 +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 })
         });
     }
-    listMessages(runId) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/messages`);
+    async listMessages(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/messages`));
     }
-    listArtifacts(runId) {
-        return this.request(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/artifacts`);
+    async listArtifacts(runId) {
+        return this.request(await this.orgPath(`/runs/${encodeURIComponent(runId)}/artifacts`));
     }
-    downloadArtifact(runId, artifactPath) {
-        return this.rawRequest(`/v1/orgs/${encodeURIComponent(this.config.org)}/runs/${encodeURIComponent(runId)}/artifacts?path=${encodeURIComponent(artifactPath)}`);
+    async downloadArtifact(runId, artifactPath) {
+        return this.rawRequest(`${await this.orgPath(`/runs/${encodeURIComponent(runId)}/artifacts`)}?path=${encodeURIComponent(artifactPath)}`);
     }
 }

package/dist/args.js

@@ -1,4 +1,4 @@
-const multiFlags = new Set(["input", "include", "artifact"]);
+const multiFlags = new Set(["input", "include", "artifact", "telegram-allowed-user"]);
 export const booleanFlags = new Set([
     "help",
     "version",

package/dist/cli.js

@@ -16,14 +16,12 @@ const help = `Sanbox CLI
 
 Environment:
   SANBOX_API_URL   Sanbox API base URL
-  SANBOX_ORG       Organization slug
   SANBOX_API_KEY   Org API key
   SANBOX_TEMPLATE  Explicit template id or slug for run and batch
 
 Commands:
   sanbox --version
   sanbox auth check [--json]
-  sanbox orgs list [--json]
   sanbox context [--json]
   sanbox doctor [--json]
   sanbox model-providers list [--json]
@@ -32,7 +30,7 @@ Commands:
   sanbox templates list [--json]
   sanbox templates get <template-id> [--json]
   sanbox templates validate <template-id> [--json]
-  sanbox templates create --name "..." --model-provider <provider-id> --model <model-id> [--llm-budget-usd <amount>] [--web-access] [--json]
+  sanbox templates create --name "..." --model-provider <provider-id> --model <model-id> [--harness opencode|hermes] [--llm-budget-usd <amount>] [--json]
   sanbox run "task" --template <template-id> [--input <path>] [--wait | --watch] [--json | --jsonl]
   sanbox run --task "..." --template <template-id> [--input <path>] [--wait | --watch] [--json | --jsonl]
   sanbox batch --tasks tasks.json --template <template-id> [--input <path>] [--max-parallel 5] [--wait] [--json]
@@ -58,7 +56,6 @@ Options:
   --input <path>                File, directory, or glob to upload. Repeatable.
   --template <id>               Template id or slug. Required unless SANBOX_TEMPLATE or project config sets it.
   --external-run-id <id>        Idempotency key for retries.
-  --retention-ttl-seconds <n>   Workspace retention TTL. Default: 86400.
   --dry-run                     Preview included files without creating a run.
   --wait                        Poll until terminal status.
   --watch                       Stream activity until terminal status.
@@ -73,7 +70,7 @@ const doctorHelp = `Sanbox doctor
 Usage:
   sanbox doctor [--json]
 
-Checks local configuration, API health, auth, org visibility, and template access.
+Checks local configuration, API health, auth, organization discovery, and template access.
 SANBOX_API_KEY is still read only from the environment.
 `;
 const modelProvidersHelp = `Sanbox model providers
@@ -92,26 +89,34 @@ Usage:
   sanbox templates list [--json]
   sanbox templates get <template-id> [--json]
   sanbox templates validate <template-id> [--json]
-  sanbox templates create --name "Code review" --model-provider <provider-id> --model <model-id> [--llm-budget-usd <amount>] [--web-access] [--json]
+  sanbox templates create --name "Code review" --model-provider <provider-id> --model <model-id> [--harness opencode|hermes] [--llm-budget-usd <amount>] [--json]
 
 Template creation requires an exact provider id and that provider's exact model id.
 LiteLLM budgets are optional USD amounts and apply separately to each run.
+Hermes templates are always-on Telegram gateways. Set SANBOX_TELEGRAM_BOT_TOKEN
+and repeat --telegram-allowed-user <numeric-id> for every permitted user.
 `;
 const agentInstructions = `# Operate Sanbox Autonomously
 
 Use the \`sanbox\` CLI for focused, isolated, long-running, risky, or parallel work. The canonical
-protocol is https://console.sanbox.cloud/agent.md. This workflow requires CLI 0.0.4 or newer.
+protocol is https://console.sanbox.cloud/agent.md.
+
+Always use the latest published CLI. Install and verify it at the start of every operating session:
+\`\`\`bash
+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"
+\`\`\`
 
 Human bootstrap:
-- A human/admin supplies SANBOX_API_KEY and configures provider credentials plus a runnable template.
+- A human/admin supplies an organization-scoped SANBOX_API_KEY and configures provider credentials plus a runnable template.
 - Never print, persist, prompt with, or upload API keys or provider credentials.
 - If the key or a runnable template is unavailable, stop with the exact human action required.
 
 Deterministic startup:
 \`\`\`bash
 sanbox --version
-sanbox orgs list --json
-export SANBOX_ORG=<returned-org-slug>
 sanbox auth check --json
 sanbox context --json
 sanbox templates list --json
@@ -120,8 +125,11 @@ sanbox templates validate "$SANBOX_TEMPLATE" --json
 sanbox doctor --json
 \`\`\`
 
-Never guess opaque IDs. Select a discovered org/template automatically only when exactly one valid
-choice exists; otherwise ask the user. Provider credentials and template administration are
+Never guess opaque IDs. The CLI derives the organization from the API key and requires the key to
+resolve to exactly one organization. For task execution, select only a template with runnable: true,
+template_type: "runner", and runner_config.harness: "opencode". Never select a Hermes service
+template for a waited task because it is always-on. Select automatically only when exactly one task
+template qualifies; otherwise ask the user. Provider credentials and template administration are
 console-only.
 
 Use --json for request/response commands and --jsonl for streams. Parse the versioned envelope:
@@ -139,7 +147,7 @@ sanbox run "Investigate one focused task and write output/report.md" \\
 
 Reuse the same --external-run-id after ambiguous failures. Retry network errors, HTTP 429, HTTP 5xx,
 and workspace_busy with bounded backoff. Do not retry other 4xx errors unless next_actions directs
-recovery.
+recovery. Terminal statuses are completed, failed, and canceled.
 
 Recover and retrieve results:
 \`\`\`bash
@@ -154,33 +162,38 @@ sanbox runs download <run-id> --output .sanbox/output/<run-id> --json
 Tasks must put durable files under /workspace/output. Downloads preserve relative paths and report
 byte counts plus SHA-256 digests; existing files require explicit --overwrite.
 
-Continue through the retained workspace:
+Continue through the same paused writable sandbox:
 \`\`\`bash
 sanbox runs messages <run-id> --json
+sanbox runs get <run-id> --json
 sanbox runs message <run-id> "Summarize the retained output" --wait --json
 \`\`\`
 
-Follow-up waits are correlated to the returned chat_job.id. Keep dependent follow-ups sequential.
+Before a follow-up, require sandbox_state: "paused" and a positive snapshot_generation. The message
+resumes the same sandbox and OpenCode session, then pauses it as a new generation. Follow-up waits
+are correlated to the returned chat_job.id. Never submit concurrent follow-ups to one run. Retry
+sandbox_not_paused only after the run returns to paused; treat sandbox_not_resumable,
+sandbox_snapshot_missing, sandbox_worker_missing, and hermes_uses_channel as blockers.
+
 For independent fan-out, use \`sanbox batch\` with a stable external_run_id per task and keep the
 client alive until submission completes.
 
 Do not claim completion until the run is completed, required artifacts are downloaded and verified,
-and required follow-ups succeeded. Report run/external/template IDs, status, artifact paths/digests,
-and blockers. The CLI excludes common secrets by default; add .sanboxignore for project rules.
+and required follow-ups succeeded. Report run/external/template IDs, status, sandbox state, snapshot
+generation, artifact paths/digests, and blockers. The CLI excludes common secrets by default; add
+.sanboxignore for project rules.
 `;
 const cwd = () => process.cwd();
 const makeClient = (flags) => new SanboxClient(readConfig(flags));
-const makeAuthClient = (flags) => new SanboxClient(readConfig(flags, { requireOrg: false }));
 const jsonContext = (client) => ({
     api_url: client.config.apiUrl,
-    org: client.config.org
+    ...(client.resolvedOrganizationSlug() ? { org: client.resolvedOrganizationSlug() } : {})
 });
 const localJsonContext = (flags) => {
     try {
         const local = readLocalConfig();
         const apiUrl = String(flags["api-url"] || process.env.SANBOX_API_URL || local.api_url || defaultApiUrl).replace(/\/+$/, "");
-        const org = String(flags.org || process.env.SANBOX_ORG || local.org || "").trim();
-        return { api_url: apiUrl, ...(org ? { org } : {}) };
+        return { api_url: apiUrl };
     }
     catch {
         return {};
@@ -191,7 +204,7 @@ const consoleUrl = (client) => consolePathUrl(client, "/model-providers");
 const providerConsoleAction = (client) => consoleAction(consoleUrl(client), "Ask an organization admin to configure or repair the model provider in the Sanbox console.");
 const templateAdminConsoleAction = (client) => consoleAction(consolePathUrl(client, "/templates"), "Ask an organization admin to create a template in the Sanbox console.");
 const templateActions = () => [
-    commandAction(["sanbox", "templates", "list", "--json"], "List templates available to the selected organization."),
+    commandAction(["sanbox", "templates", "list", "--json"], "List templates available to the API key's organization."),
     commandAction(["sanbox", "templates", "validate", "<template-id>", "--json"], "Check whether a template is runnable.")
 ];
 const runReadinessCodes = new Set([
@@ -273,10 +286,9 @@ const formatBytes = (bytes) => {
 };
 const positionalText = (command, startIndex) => command.slice(startIndex).join(" ").trim();
 const runTask = (command, flags) => flagString(flags, "task") || positionalText(command, 1);
-const commonFlags = ["api-url", "org", "json", "help"];
+const commonFlags = ["api-url", "json", "help"];
 const flagSets = {
     "auth.check": commonFlags,
-    "orgs.list": commonFlags,
     context: [...commonFlags, "template"],
     doctor: [...commonFlags, "template"],
     "model-providers.list": commonFlags,
@@ -285,15 +297,24 @@ const flagSets = {
     "templates.list": commonFlags,
     "templates.get": commonFlags,
     "templates.validate": commonFlags,
-    "templates.create": [...commonFlags, "name", "model-provider", "model", "llm-budget-usd", "web-access"],
+    "templates.create": [
+        ...commonFlags,
+        "name",
+        "model-provider",
+        "model",
+        "harness",
+        "llm-budget-usd",
+        "web-access",
+        "telegram-allowed-user"
+    ],
     run: [
-        ...commonFlags, "task", "input", "template", "external-run-id", "retention-ttl-seconds",
+        ...commonFlags, "task", "input", "template", "external-run-id",
         "dry-run", "wait", "watch", "jsonl", "view", "after-event-id", "cancel-on-interrupt",
         "poll-interval-ms", "event-page-size", "timeout-seconds", "verbose"
     ],
     batch: [
         ...commonFlags, "tasks", "template", "input", "max-parallel", "wait", "batch-id",
-        "retention-ttl-seconds", "poll-interval-ms", "timeout-seconds"
+        "poll-interval-ms", "timeout-seconds"
     ],
     "runs.list": [...commonFlags, "limit"],
     "runs.get": commonFlags,
@@ -321,8 +342,6 @@ const commandKey = (command) => {
         return "version";
     if (command[0] === "auth")
         return `auth.${command[1] || ""}`;
-    if (command[0] === "orgs")
-        return `orgs.${command[1] || ""}`;
     if (command[0] === "model-providers" || command[0] === "templates" || command[0] === "runs") {
         return `${command[0]}.${command[1] || ""}`;
     }
@@ -331,10 +350,11 @@ const commandKey = (command) => {
     return command[0];
 };
 const requiredValueFlags = new Set([
-    "api-url", "org", "template", "task", "input", "include", "external-run-id",
-    "retention-ttl-seconds", "tasks", "max-parallel", "batch-id", "poll-interval-ms",
+    "api-url", "template", "task", "input", "include", "external-run-id",
+    "tasks", "max-parallel", "batch-id", "poll-interval-ms",
     "event-page-size", "timeout-seconds", "view", "after-event-id", "limit", "name",
-    "model-provider", "model", "llm-budget-usd", "message", "output", "artifact"
+    "model-provider", "model", "harness", "llm-budget-usd", "telegram-allowed-user",
+    "message", "output", "artifact"
 ]);
 const validateFlagValues = (flags) => {
     for (const flag of requiredValueFlags) {
@@ -372,7 +392,7 @@ const validateFlags = (command, flags) => {
         return;
     }
     const knownRoots = new Set([
-        "auth", "orgs", "context", "doctor", "model-providers", "templates",
+        "auth", "context", "doctor", "model-providers", "templates",
         "run", "batch", "runs", "init", "version"
     ]);
     const allowed = flagSets[key] ?? (knownRoots.has(command[0] || "") ? commonFlags : null);
@@ -388,7 +408,6 @@ const validatePositionals = (command, flags) => {
         return;
     const maximums = {
         "auth.check": 2,
-        "orgs.list": 2,
         context: 1,
         doctor: 1,
         "model-providers.list": 2,
@@ -533,8 +552,7 @@ const commandRun = async (command, flags) => {
             instruction: task,
             inputs: flagList(flags, "input"),
             externalRunId: flagString(flags, "external-run-id") || undefined,
-            templateId: template.id,
-            retentionTtlSeconds: integerFlag(flags, "retention-ttl-seconds", 86400, 0, Number.MAX_SAFE_INTEGER)
+            templateId: template.id
         });
     }
     catch (error) {
@@ -587,8 +605,7 @@ const commandBatch = async (flags) => {
                 instruction: task.task,
                 inputs: task.input || inputs,
                 externalRunId: task.external_run_id || `sanbox-batch-${batchId}-${index + 1}`,
-                templateId: template.id,
-                retentionTtlSeconds: integerFlag(flags, "retention-ttl-seconds", 86400, 0, Number.MAX_SAFE_INTEGER)
+                templateId: template.id
             });
         }
         catch (error) {
@@ -617,50 +634,28 @@ const commandBatch = async (flags) => {
 };
 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 };
+    const [me, selected] = await Promise.all([client.me(), client.organization()]);
+    const org = selected.slug;
+    const output = { ok: true, org, selected, me };
     if (hasFlag(flags, "json"))
         printSuccess("auth.check", output, jsonContext(client));
     else
-        process.stdout.write(selected ? `ok org=${org}\n` : `authenticated, but org ${org} is not visible\n`);
-    if (!selected)
-        process.exitCode = 2;
-};
-const commandOrganizations = async (command, flags) => {
-    if (command[1] !== "list")
-        throw new CliError("orgs_action_required", "orgs requires the list action.");
-    const client = makeAuthClient(flags);
-    const payload = await client.listOrganizations();
-    if (hasFlag(flags, "json")) {
-        printSuccess("orgs.list", payload, { api_url: client.config.apiUrl });
-        return;
-    }
-    for (const organization of payload.organizations) {
-        process.stdout.write(`${organization.slug}${organization.name ? `\t${organization.name}` : ""}${organization.membership_role ? `\t${organization.membership_role}` : ""}\n`);
-    }
+        process.stdout.write(`ok org=${org}\n`);
 };
 const commandContext = async (flags) => {
     const client = makeClient(flags);
     const selection = readTemplateSelection(flags, { required: false });
-    const [me, providerPayload, templatePayload] = await Promise.all([
+    const [organization, me, providerPayload, templatePayload] = await Promise.all([
+        client.organization(),
         client.me(),
         client.listModelProviders(),
         client.listTemplates()
     ]);
-    const organizations = Array.isArray(me.organizations)
-        ? me.organizations
-        : [];
-    const selectedOrganization = organizations.find((item) => item.slug === client.config.org) || null;
     const selectedTemplate = selection
         ? templatePayload.templates.find((item) => item.id === selection.id || item.template_slug === selection.id) || null
         : null;
     const output = {
-        organization: selectedOrganization,
+        organization,
         authentication: me.auth || null,
         template_selection: selection
             ? { id: selection.id, source: selection.source, found: Boolean(selectedTemplate), template: selectedTemplate }
@@ -669,22 +664,17 @@ const commandContext = async (flags) => {
         templates: templatePayload.templates
     };
     const nextActions = [];
-    if (!selectedOrganization) {
-        nextActions.push(commandAction(["sanbox", "auth", "check", "--json"], "Verify that the API key can access the selected organization."));
-    }
     if (!selection) {
         nextActions.push(commandAction(["sanbox", "templates", "list", "--json"], "List available templates."), commandAction(["sanbox", "context", "--json"], "Select a template for this shell and inspect the resolved context.", { SANBOX_TEMPLATE: "<template-id>" }));
     }
     else if (!selectedTemplate) {
         nextActions.push(commandAction(["sanbox", "templates", "list", "--json"], "Choose a template that exists in this organization."));
     }
-    if (!selectedOrganization)
-        process.exitCode = 2;
     if (hasFlag(flags, "json")) {
         printSuccess("context.get", output, jsonContext(client), nextActions);
         return;
     }
-    process.stdout.write(`org=${client.config.org}\n`);
+    process.stdout.write(`org=${organization.slug}\n`);
     process.stdout.write(`template=${selection ? `${selection.id} source=${selection.source}${selectedTemplate ? "" : " missing"}` : "not selected"}\n`);
     process.stdout.write(`model_providers=${providerPayload.providers.map((item) => providerId(item)).filter(Boolean).join(",") || "none"}\n`);
     process.stdout.write(`templates=${templatePayload.templates.map((item) => item.template_slug || item.id).join(",") || "none"}\n`);
@@ -767,7 +757,7 @@ const commandTemplates = async (command, flags) => {
         const payload = await client.listTemplates();
         const nextActions = payload.templates.length === 0
             ? [
-                commandAction(["sanbox", "context", "--json"], "Inspect the selected organization and current authentication role."),
+                commandAction(["sanbox", "context", "--json"], "Inspect the API key's organization and current authentication role."),
                 templateAdminConsoleAction(client)
             ]
             : [];
@@ -791,7 +781,7 @@ const commandTemplates = async (command, flags) => {
                 throw new CliError("template_not_found", error.message, {
                     status: error.status,
                     details: { template_id: id },
-                    nextActions: [commandAction(["sanbox", "templates", "list", "--json"], "List templates available to the selected organization.")]
+                    nextActions: [commandAction(["sanbox", "templates", "list", "--json"], "List templates available to the API key's organization.")]
                 });
             }
             throw error;
@@ -814,7 +804,7 @@ const commandTemplates = async (command, flags) => {
                 throw new CliError("template_validation_failed", error.message, {
                     status: error.status,
                     details: { template_id: id },
-                    nextActions: [commandAction(["sanbox", "templates", "list", "--json"], "List templates available to the selected organization.")]
+                    nextActions: [commandAction(["sanbox", "templates", "list", "--json"], "List templates available to the API key's organization.")]
                 });
             }
             throw error;
@@ -835,6 +825,10 @@ const commandTemplates = async (command, flags) => {
         const name = requiredPositional(flagString(flags, "name"), "template_name_required", "templates create requires --name.");
         const modelProvider = requiredPositional(flagString(flags, "model-provider"), "model_provider_required", "templates create requires --model-provider.");
         const model = requiredPositional(flagString(flags, "model"), "model_required", "templates create requires --model.");
+        const harness = flagString(flags, "harness", "opencode");
+        if (harness !== "opencode" && harness !== "hermes") {
+            throw new CliError("invalid_harness", "templates create --harness must be opencode or hermes.");
+        }
         const budgetRaw = flagString(flags, "llm-budget-usd");
         const parsedBudgetUsd = budgetRaw ? Number(budgetRaw) : undefined;
         const llmBudgetUsd = parsedBudgetUsd === undefined
@@ -844,14 +838,29 @@ const commandTemplates = async (command, flags) => {
             (!Number.isFinite(parsedBudgetUsd) || llmBudgetUsd <= 0 || llmBudgetUsd > 100_000)) {
             throw new CliError("invalid_llm_budget", "templates create --llm-budget-usd must be at least 0.000001 and no more than 100000.");
         }
+        if (harness === "hermes" && llmBudgetUsd !== undefined) {
+            throw new CliError("hermes_budget_unsupported", "Always-on Hermes templates do not support --llm-budget-usd yet.");
+        }
+        const telegramBotToken = process.env.SANBOX_TELEGRAM_BOT_TOKEN?.trim() || "";
+        const telegramAllowedUsers = flagList(flags, "telegram-allowed-user").map((value) => value.trim()).filter(Boolean);
+        if (harness === "hermes" && !telegramBotToken) {
+            throw new CliError("telegram_bot_token_required", "Hermes template creation requires SANBOX_TELEGRAM_BOT_TOKEN.");
+        }
+        if (harness === "hermes" && telegramAllowedUsers.length === 0) {
+            throw new CliError("telegram_allowed_user_required", "Hermes template creation requires at least one --telegram-allowed-user.");
+        }
         let payload;
         try {
             payload = await client.createTemplate({
                 name,
                 provider_id: modelProvider,
                 model_id: model,
-                web_access: hasFlag(flags, "web-access"),
-                ...(llmBudgetUsd === undefined ? {} : { llm_budget_usd: llmBudgetUsd })
+                ...(llmBudgetUsd === undefined ? {} : { llm_budget_usd: llmBudgetUsd }),
+                ...(harness === "hermes" ? {
+                    harness,
+                    telegram_bot_token: telegramBotToken,
+                    telegram_allowed_users: telegramAllowedUsers
+                } : {})
             });
         }
         catch (error) {
@@ -860,7 +869,9 @@ const commandTemplates = async (command, flags) => {
         if (hasFlag(flags, "json")) {
             printSuccess("templates.create", payload, jsonContext(client), [
                 commandAction(["sanbox", "templates", "validate", payload.template.id, "--json"], "Validate the new template before running it."),
-                commandAction(["sanbox", "run", "<task>", "--template", payload.template.id], "Create a run with the new template.")
+                commandAction(["sanbox", "run", harness === "hermes" ? "<agent role and instructions>" : "<task>", "--template", payload.template.id], harness === "hermes"
+                    ? "Start the always-on gateway; interact with it through the configured Telegram bot."
+                    : "Create a run with the new template.")
             ]);
             return;
         }
@@ -1096,9 +1107,9 @@ const commandRuns = async (command, flags) => {
 const commandDoctor = async (flags) => {
     const localConfig = readLocalConfig();
     const apiUrl = String(flags["api-url"] || process.env.SANBOX_API_URL || localConfig.api_url || defaultApiUrl).replace(/\/+$/, "");
-    const org = String(flags.org || process.env.SANBOX_ORG || localConfig.org || "").trim();
     const apiKey = process.env.SANBOX_API_KEY || "";
     const selection = readTemplateSelection(flags, { required: false });
+    let resolvedOrg = "";
     const checks = [];
     const nextActions = [];
     const add = (name, ok, detail, data) => checks.push({
@@ -1109,11 +1120,7 @@ const commandDoctor = async (flags) => {
     });
     add("node", Number(process.versions.node.split(".")[0]) >= 20, process.version);
     add("api_url", Boolean(apiUrl), apiUrl);
-    add("org", Boolean(org), org || "missing SANBOX_ORG, --org, or .sanbox/config.json org");
     add("api_key", Boolean(apiKey), apiKey ? "present in environment" : "missing SANBOX_API_KEY");
-    if (!org) {
-        nextActions.push(commandAction(["sanbox", "doctor", "--json"], "Select an organization and run the checks again.", { SANBOX_ORG: "<org-slug>" }));
-    }
     if (!apiKey) {
         nextActions.push(commandAction(["sanbox", "doctor", "--json"], "Set a Sanbox control-plane API key and run the checks again.", { SANBOX_API_KEY: "<sanbox-api-key>" }));
     }
@@ -1124,50 +1131,50 @@ const commandDoctor = async (flags) => {
     catch (error) {
         add("api_health", false, error instanceof Error ? error.message : String(error));
     }
-    if (org && apiKey) {
-        const client = new SanboxClient({ apiUrl, org, apiKey });
+    if (apiKey) {
+        const client = new SanboxClient({ apiUrl, apiKey });
         try {
-            const me = await client.me();
-            const organizations = Array.isArray(me.organizations)
-                ? me.organizations
-                : [];
+            const organization = await client.organization();
+            resolvedOrg = organization.slug;
             add("auth", true, "authenticated");
-            add("org_visible", organizations.some((item) => item.slug === org), org);
+            add("organization", true, organization.slug, organization);
         }
         catch (error) {
             add("auth", false, error instanceof Error ? error.message : String(error));
         }
-        try {
-            const providers = await client.listModelProviders();
-            add("model_providers", true, providers.providers.map((item) => `${providerId(item)}:${item.status || (item.configured ? "configured" : "not_configured")}`).join(", ") || "none", providers.providers);
-        }
-        catch (error) {
-            add("model_providers", false, error instanceof Error ? error.message : String(error));
-        }
-        if (!selection) {
-            add("template", false, "not selected; use --template, SANBOX_TEMPLATE, or .sanbox/config.json default_template");
-            nextActions.push(...templateActions());
-        }
-        else {
+        if (resolvedOrg) {
             try {
-                const template = await client.getTemplate(selection.id);
-                add("template", true, `${template.template.id}; source=${selection.source}`, template.template);
+                const providers = await client.listModelProviders();
+                add("model_providers", true, providers.providers.map((item) => `${providerId(item)}:${item.status || (item.configured ? "configured" : "not_configured")}`).join(", ") || "none", providers.providers);
+            }
+            catch (error) {
+                add("model_providers", false, error instanceof Error ? error.message : String(error));
+            }
+            if (!selection) {
+                add("template", false, "not selected; use --template, SANBOX_TEMPLATE, or .sanbox/config.json default_template");
+                nextActions.push(...templateActions());
+            }
+            else {
                 try {
-                    const validation = await client.validateTemplate(selection.id);
-                    const runnable = validationRunnable(validation);
-                    add("template_readiness", runnable, runnable ? "ready" : "blocked", validation);
-                    if (!runnable) {
-                        nextActions.push(commandAction(["sanbox", "model-providers", "list", "--json"], "Inspect model-provider status."), providerConsoleAction(client));
+                    const template = await client.getTemplate(selection.id);
+                    add("template", true, `${template.template.id}; source=${selection.source}`, template.template);
+                    try {
+                        const validation = await client.validateTemplate(selection.id);
+                        const runnable = validationRunnable(validation);
+                        add("template_readiness", runnable, runnable ? "ready" : "blocked", validation);
+                        if (!runnable) {
+                            nextActions.push(commandAction(["sanbox", "model-providers", "list", "--json"], "Inspect model-provider status."), providerConsoleAction(client));
+                        }
+                    }
+                    catch (error) {
+                        add("template_readiness", false, error instanceof Error ? error.message : String(error));
                     }
                 }
                 catch (error) {
-                    add("template_readiness", false, error instanceof Error ? error.message : String(error));
+                    add("template", false, error instanceof Error ? error.message : String(error));
+                    nextActions.push(...templateActions());
                 }
             }
-            catch (error) {
-                add("template", false, error instanceof Error ? error.message : String(error));
-                nextActions.push(...templateActions());
-            }
         }
     }
     try {
@@ -1183,7 +1190,7 @@ const commandDoctor = async (flags) => {
         checks
     };
     if (hasFlag(flags, "json")) {
-        printSuccess("doctor", output, { api_url: apiUrl, ...(org ? { org } : {}) }, nextActions);
+        printSuccess("doctor", output, { api_url: apiUrl, ...(resolvedOrg ? { org: resolvedOrg } : {}) }, nextActions);
     }
     else {
         for (const check of checks) {
@@ -1220,11 +1227,9 @@ const commandInit = async (command, flags) => {
     const force = hasFlag(flags, "force");
     const localConfig = readLocalConfig();
     const apiUrl = String(flags["api-url"] || process.env.SANBOX_API_URL || localConfig.api_url || defaultApiUrl).replace(/\/+$/, "");
-    const org = String(flags.org || process.env.SANBOX_ORG || localConfig.org || "").trim();
     const template = readTemplateSelection(flags, { required: false });
     const config = {
         api_url: apiUrl,
-        org,
         ...(template ? { default_template: template.id } : {})
     };
     const sanboxIgnore = [
@@ -1245,7 +1250,7 @@ const commandInit = async (command, flags) => {
         printSuccess("init", {
             files: results.map(([file, status]) => ({ file, status })),
             template_selection: template
-        }, { api_url: apiUrl, ...(org ? { org } : {}) }, template ? [] : templateActions());
+        }, { api_url: apiUrl }, template ? [] : templateActions());
     }
     else {
         for (const [file, status] of results)
@@ -1268,8 +1273,6 @@ const commandId = (command) => {
         return "version";
     if (command[0] === "auth")
         return "auth.check";
-    if (command[0] === "orgs")
-        return `orgs.${command[1] || "unknown"}`;
     if (command[0] === "context")
         return "context.get";
     if (command[0] === "model-providers")
@@ -1306,8 +1309,6 @@ const main = async (command, flags) => {
     }
     if (command[0] === "auth" && command[1] === "check")
         return commandAuthCheck(flags);
-    if (command[0] === "orgs")
-        return commandOrganizations(command, flags);
     if (command[0] === "context")
         return commandContext(flags);
     if (command[0] === "doctor")

package/dist/config.js

@@ -11,7 +11,6 @@ export const readLocalConfig = (cwd = process.cwd()) => {
         const record = parsed;
         return {
             api_url: typeof record.api_url === "string" ? record.api_url : undefined,
-            org: typeof record.org === "string" ? record.org : undefined,
             default_template: typeof record.default_template === "string" ? record.default_template : undefined
         };
     }
@@ -21,22 +20,16 @@ export const readLocalConfig = (cwd = process.cwd()) => {
         throw error;
     }
 };
-export const readConfig = (flags = {}, options = {}) => {
+export const readConfig = (flags = {}) => {
     const localConfig = readLocalConfig();
     const apiUrl = String(flags["api-url"] || process.env.SANBOX_API_URL || localConfig.api_url || defaultApiUrl).replace(/\/+$/, "");
-    const org = String(flags.org || process.env.SANBOX_ORG || localConfig.org || "").trim();
     const apiKey = process.env.SANBOX_API_KEY || "";
-    if (options.requireOrg !== false && !org) {
-        throw new CliError("org_required", "Organization context is required.", {
-            nextActions: [commandAction(["sanbox", "context", "--json"], "Select an organization and retry with SANBOX_ORG set.", { SANBOX_ORG: "<org-slug>" })]
-        });
-    }
     if (!apiKey) {
         throw new CliError("api_key_required", "SANBOX_API_KEY is required.", {
             nextActions: [commandAction(["sanbox", "auth", "check", "--json"], "Set a Sanbox control-plane API key and check access.", { SANBOX_API_KEY: "<sanbox-api-key>" })]
         });
     }
-    return { apiUrl, org, apiKey };
+    return { apiUrl, apiKey };
 };
 export function readTemplateSelection(flags = {}, options = {}) {
     const flagValue = flags.template;
@@ -52,7 +45,7 @@ export function readTemplateSelection(flags = {}, options = {}) {
         return null;
     throw new CliError("template_required", "A template must be selected explicitly.", {
         nextActions: [
-            commandAction(["sanbox", "templates", "list", "--json"], "List templates available to the selected organization."),
+            commandAction(["sanbox", "templates", "list", "--json"], "List templates available to the API key's organization."),
             commandAction(["sanbox", "run", "<task>", "--template", "<template-id>"], "Run with an explicit template."),
             commandAction(["sanbox", "context", "--json"], "Select a template for this shell and inspect the resolved context.", { SANBOX_TEMPLATE: "<template-id>" })
         ]

package/dist/output.js

@@ -77,7 +77,9 @@ export const summarizeRun = (payload) => {
     const selection = [
         templateId ? `template=${templateId}` : "",
         run.provider_id ? `provider=${run.provider_id}` : "",
-        run.model_id ? `model=${run.model_id}` : ""
+        run.model_id ? `model=${run.model_id}` : "",
+        run.sandbox_state ? `sandbox=${run.sandbox_state}` : "",
+        run.snapshot_generation ? `snapshot=${run.snapshot_generation}` : ""
     ].filter(Boolean).join(" ");
     return `${run.id} ${run.status}${selection ? ` ${selection}` : ""}${run.exit_code === null ? "" : ` exit=${run.exit_code}`}${run.error ? ` error=${run.error}` : ""}`;
 };

package/dist/runs.js

@@ -2,7 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { buildInputBundle } from "./inputs.js";
-const terminalStatuses = new Set(["completed", "failed", "canceled", "expired"]);
+const terminalStatuses = new Set(["completed", "failed", "canceled"]);
 export const isTerminalRun = (run) => terminalStatuses.has(run.status);
 export const waitForRun = async (client, runId, options = {}) => {
     const pollIntervalMs = options.pollIntervalMs ?? 2000;
@@ -31,8 +31,7 @@ export const createRun = async (client, options) => {
         external_run_id: options.externalRunId,
         workload_id: options.templateId,
         instruction: options.instruction,
-        ...(inputCollectionId ? { input_collection_id: inputCollectionId } : {}),
-        retention_ttl_seconds: options.retentionTtlSeconds
+        ...(inputCollectionId ? { input_collection_id: inputCollectionId } : {})
     });
 };
 export const readTasks = async (tasksPath) => {

package/dist/version.js

@@ -1 +1 @@
-export const version = "0.0.4";
+export const version = "0.0.5";

package/dist/watch.js

@@ -1,6 +1,6 @@
 import { SanboxApiError } from "./api.js";
-const terminalStatuses = new Set(["completed", "failed", "canceled", "expired"]);
-const terminalEventKinds = new Set(["run.completed", "run.failed", "run.canceled", "run.expired"]);
+const terminalStatuses = new Set(["completed", "failed", "canceled"]);
+const terminalEventKinds = new Set(["run.completed", "run.failed", "run.canceled"]);
 const retryableNetworkCodes = new Set(["ECONNRESET", "ECONNREFUSED", "EPIPE", "ETIMEDOUT", "EAI_AGAIN", "ENETUNREACH"]);
 export class WatchInterruptedError extends Error {
     constructor() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanlabs/sanbox-cli",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "private": false,
   "repository": {
     "type": "git",