@sanlabs/sanbox-cli 0.0.1 → 0.0.3

package/dist/cli.js

@@ -1,30 +1,110 @@
 #!/usr/bin/env node
 import fs from "node:fs/promises";
 import path from "node:path";
+import { formatActivityJsonl, formatActivityLine, parseActivityView, shouldRenderEvent } from "./activity.js";
 import { flagList, flagNumber, flagString, hasFlag, parseArgs } from "./args.js";
-import { SanboxClient } from "./api.js";
-import { defaultWorkloadId, readConfig } from "./config.js";
-import { printJson, printRun } from "./output.js";
+import { SanboxApiError, SanboxClient } from "./api.js";
+import { defaultApiUrl, readConfig, readLocalConfig, readTemplateSelection } from "./config.js";
+import { inspectDossierFile, previewTaskDossier, writeTaskDossier } from "./dossier.js";
+import { CliError, commandAction, consoleAction } from "./errors.js";
+import { printError, printJsonlError, printRun, printSuccess, publicRun, publicRunPayload } from "./output.js";
 import { createRun, isTerminalRun, readTasks, runPool, stableBatchId, waitForRun } from "./runs.js";
 import { version } from "./version.js";
+import { WatchInterruptedError, watchRun } from "./watch.js";
 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 auth check [--json]
-  sanbox run --task "..." [--include "app/**"] [--wait] [--json]
-  sanbox run --dossier ./task.zip [--wait] [--json]
-  sanbox batch --tasks tasks.json [--include "app/**"] [--max-parallel 5] [--wait] [--json]
+  sanbox context [--json]
+  sanbox doctor [--json]
+  sanbox model-providers list [--json]
+  sanbox model-providers get <provider-id> [--json]
+  sanbox model-providers models <provider-id> [--json]
+  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> [--web-access] [--json]
+  sanbox run "task" --template <template-id> [--include "app/**"] [--wait | --watch] [--json | --jsonl]
+  sanbox run --task "..." --template <template-id> [--include "app/**"] [--wait | --watch] [--json | --jsonl]
+  sanbox run --dossier ./task.zip --template <template-id> [--wait | --watch] [--json | --jsonl]
+  sanbox batch --tasks tasks.json --template <template-id> [--include "app/**"] [--max-parallel 5] [--wait] [--json]
+  sanbox bundle preview [--include "app/**"] [--json]
+  sanbox bundle create "task" --out ./run.zip [--include "app/**"]
+  sanbox bundle inspect ./run.zip [--json]
   sanbox runs get <run-id> [--json]
   sanbox runs events <run-id> [--after-event-id 0] [--json]
+  sanbox runs watch <run-id> [--after-event-id 0] [--view activity|logs|compact] [--jsonl]
   sanbox runs cancel <run-id> [--json]
   sanbox runs message <run-id> --message "..." [--json]
+  sanbox init [--force]
   sanbox init agent [--write]
 `;
+const runHelp = `Sanbox run
+
+Usage:
+  sanbox run "Review this code" --template <template-id> --include "app/**" --wait
+  sanbox run --task "Review this code" --template <template-id> --include "app/**" --wait --json
+  sanbox run --dossier ./run.zip --template <template-id> --wait
+
+Options:
+  --include <glob>              File glob or directory to include. Repeatable.
+  --dossier <path>              Submit an existing dossier/run-bundle ZIP.
+  --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.
+  --jsonl                       Stream one versioned activity event per line. Implies --watch.
+  --view <name>                 activity, logs, or compact. Default: activity.
+  --after-event-id <id>         Resume after an event cursor. Default: 0.
+  --cancel-on-interrupt         Request run cancellation when Ctrl-C is pressed.
+  --json                        Print JSON.
+`;
+const bundleHelp = `Sanbox bundle
+
+Usage:
+  sanbox bundle preview --include "app/**"
+  sanbox bundle create "Review this repo" --include "app/**" --out ./run.zip
+  sanbox bundle inspect ./run.zip
+
+Bundle is the public name for the portable ZIP contract. The runner still accepts
+the same ZIP dossier shape: RUNBOOK.md, manifest.json, and input/.
+`;
+const doctorHelp = `Sanbox doctor
+
+Usage:
+  sanbox doctor [--json]
+
+Checks local configuration, API health, auth, org visibility, and template access.
+SANBOX_API_KEY is still read only from the environment.
+`;
+const modelProvidersHelp = `Sanbox model providers
+
+Usage:
+  sanbox model-providers list [--json]
+  sanbox model-providers get <provider-id> [--json]
+  sanbox model-providers models <provider-id> [--json]
+
+Provider credentials are configured by organization admins in the Sanbox console.
+Model ids are scoped to their provider and are never deduplicated across providers.
+`;
+const templatesHelp = `Sanbox templates
+
+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> [--web-access] [--json]
+
+Template creation requires an exact provider id and that provider's exact model id.
+`;
 const agentInstructions = `# Sanbox Agent Integration
 
 Use Sanbox when a task is independent, long-running, risky to run locally, or can be split into parallel subtasks.
@@ -33,45 +113,285 @@ Environment expected by the CLI:
 - SANBOX_API_URL
 - SANBOX_ORG
 - SANBOX_API_KEY
+- SANBOX_TEMPLATE, or an explicit --template flag/project default
 
 Useful commands:
 \`\`\`bash
 sanbox auth check
-sanbox run --task "Investigate one focused task" --include "app/**" --wait --json
-sanbox batch --tasks .sanbox/tasks.json --include "app/**" --max-parallel 5 --wait --json
+sanbox doctor
+sanbox context --json
+sanbox model-providers list --json
+sanbox model-providers models <provider-id> --json
+sanbox templates list --json
+sanbox templates validate <template-id> --json
+sanbox run "Investigate one focused task" --template <template-id> --include "app/**" --watch
+sanbox batch --tasks .sanbox/tasks.json --template <template-id> --include "app/**" --max-parallel 5 --wait --json
 sanbox runs get <run-id> --json
+sanbox runs watch <run-id>
 sanbox runs events <run-id> --json
 sanbox runs message <run-id> --message "Summarize the retained output" --json
 \`\`\`
 
-Do not put secrets in dossiers. The CLI excludes common env and secret-like filenames by default.
+Do not put secrets in run bundles. The CLI excludes common env and secret-like filenames by default.
+Provider credentials are console-only and must never be passed in CLI flags or prompts.
 `;
 const cwd = () => process.cwd();
 const makeClient = (flags) => new SanboxClient(readConfig(flags));
-const commandRun = async (flags) => {
-    const client = makeClient(flags);
-    const task = flagString(flags, "task");
+const jsonContext = (client) => ({
+    api_url: client.config.apiUrl,
+    org: client.config.org
+});
+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 } : {}) };
+    }
+    catch {
+        return {};
+    }
+};
+const consolePathUrl = (client, pathname) => new URL(pathname, `${client.config.apiUrl}/`).toString();
+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", "validate", "<template-id>", "--json"], "Check whether a template is runnable.")
+];
+const runReadinessCodes = new Set([
+    "provider_not_configured",
+    "provider_invalid",
+    "model_not_found_for_provider",
+    "template_provider_missing",
+    "template_not_runnable"
+]);
+const providerReadinessCodes = new Set([
+    "provider_not_configured",
+    "provider_invalid",
+    "model_not_found_for_provider",
+    "template_provider_missing"
+]);
+const runCreationError = (error, client, template) => {
+    if (!(error instanceof SanboxApiError) || !runReadinessCodes.has(error.code))
+        return error;
+    const nextActions = [
+        commandAction(["sanbox", "templates", "validate", template.id, "--json"], "Inspect the selected template's current provider/model blockers."),
+        commandAction(["sanbox", "model-providers", "list", "--json"], "Inspect organization-scoped model-provider status.")
+    ];
+    if (providerReadinessCodes.has(error.code))
+        nextActions.push(providerConsoleAction(client));
+    return new CliError(error.code, error.message, {
+        status: error.status,
+        details: { template_id: template.id },
+        nextActions
+    });
+};
+const templateCreationError = (error, client, providerId, modelId) => {
+    if (!(error instanceof SanboxApiError))
+        return error;
+    if (error.code === "provider_not_configured" || error.code === "provider_invalid") {
+        return new CliError(error.code, error.message, {
+            status: error.status,
+            details: { provider_id: providerId, model_id: modelId },
+            nextActions: [
+                commandAction(["sanbox", "model-providers", "get", providerId, "--json"], "Inspect the selected provider's organization-scoped status."),
+                providerConsoleAction(client)
+            ]
+        });
+    }
+    if (error.code === "model_not_found_for_provider") {
+        return new CliError(error.code, error.message, {
+            status: error.status,
+            details: { provider_id: providerId, model_id: modelId },
+            nextActions: [commandAction(["sanbox", "model-providers", "models", providerId, "--json"], "List exact selectable and non-selectable model ids exposed by the selected provider.")]
+        });
+    }
+    if (error.code === "template_name_conflict") {
+        return new CliError(error.code, error.message, {
+            status: error.status,
+            nextActions: [commandAction(["sanbox", "templates", "list", "--json"], "Inspect existing template names and identifiers.")]
+        });
+    }
+    return error;
+};
+const requiredPositional = (value, code, message) => {
+    const normalized = value?.trim();
+    if (!normalized)
+        throw new CliError(code, message);
+    return normalized;
+};
+const providerId = (provider) => String(provider.provider_id || provider.id || "");
+const templateName = (template) => String(template.display_name || template.template_slug || template.id || "");
+const validationRunnable = (validation) => {
+    if (typeof validation.runnable === "boolean")
+        return validation.runnable;
+    const template = validation.template;
+    return Boolean(template && typeof template === "object" && !Array.isArray(template) && template.runnable);
+};
+const formatBytes = (bytes) => {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+};
+const positionalText = (command, startIndex) => command.slice(startIndex).join(" ").trim();
+const runTask = (command, flags) => flagString(flags, "task") || positionalText(command, 1);
+const bundleTask = (command, flags) => flagString(flags, "task") || positionalText(command, 2);
+const wantsWatch = (flags) => hasFlag(flags, "watch") || hasFlag(flags, "jsonl");
+const integerFlag = (flags, key, fallback, minimum, maximum) => {
+    if (flags[key] === undefined)
+        return fallback;
+    const value = Number(flagString(flags, key));
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new Error(`--${key} must be an integer between ${minimum} and ${maximum}.`);
+    }
+    return value;
+};
+const validateWatchFlags = (flags) => {
+    if (!wantsWatch(flags))
+        return;
+    if (hasFlag(flags, "json"))
+        throw new Error("--json cannot be combined with --watch or --jsonl.");
+    parseActivityView(flagString(flags, "view", "activity"));
+    integerFlag(flags, "after-event-id", 0, 0, Number.MAX_SAFE_INTEGER);
+    integerFlag(flags, "event-page-size", 200, 1, 500);
+    integerFlag(flags, "poll-interval-ms", 2000, 250, 60_000);
+    integerFlag(flags, "timeout-seconds", 1800, 1, 604_800);
+};
+const watchRunWithOutput = async (client, runId, flags, initialPayload) => {
+    validateWatchFlags(flags);
+    const initial = initialPayload ?? await client.getRun(runId);
+    const view = parseActivityView(flagString(flags, "view", "activity"));
+    const jsonl = hasFlag(flags, "jsonl");
+    const controller = new AbortController();
+    const onInterrupt = () => controller.abort();
+    process.once("SIGINT", onInterrupt);
+    if (!jsonl)
+        process.stdout.write(`Watching run ${runId}. Ctrl-C detaches without canceling.\n`);
+    try {
+        return await watchRun(client, runId, {
+            afterEventId: integerFlag(flags, "after-event-id", 0, 0, Number.MAX_SAFE_INTEGER),
+            pageSize: integerFlag(flags, "event-page-size", 200, 1, 500),
+            pollIntervalMs: integerFlag(flags, "poll-interval-ms", 2000, 250, 60_000),
+            timeoutSeconds: integerFlag(flags, "timeout-seconds", 1800, 1, 604_800),
+            signal: controller.signal,
+            onRetry: ({ error, attempt, delayMs }) => {
+                const message = error instanceof Error ? error.message : String(error);
+                process.stderr.write(`Watch connection lost (${message}); retry ${attempt} in ${delayMs}ms.\n`);
+            },
+            onEvent: (event) => {
+                if (!shouldRenderEvent(event, view))
+                    return;
+                process.stdout.write(`${jsonl ? formatActivityJsonl(event) : formatActivityLine(event, initial.run.created_at)}\n`);
+            }
+        });
+    }
+    catch (error) {
+        if (!(error instanceof WatchInterruptedError))
+            throw error;
+        if (hasFlag(flags, "cancel-on-interrupt")) {
+            await client.cancelRun(runId);
+            process.stderr.write(`Cancellation requested for run ${runId}.\n`);
+        }
+        else {
+            process.stderr.write(`Detached from run ${runId}; the run is still active.\n`);
+        }
+        process.exitCode = 130;
+        return null;
+    }
+    finally {
+        process.off("SIGINT", onInterrupt);
+    }
+};
+const printPreview = (preview, verbose) => {
+    process.stdout.write(`Matched ${preview.files.length} files (${formatBytes(preview.totalBytes)})\n`);
+    process.stdout.write(`Patterns: ${preview.patterns.join(", ")}\n`);
+    const files = verbose ? preview.files : preview.files.slice(0, 30);
+    for (const file of files)
+        process.stdout.write(`  ${file.path} ${formatBytes(file.size)}\n`);
+    if (!verbose && preview.files.length > files.length) {
+        process.stdout.write(`  ... ${preview.files.length - files.length} more files. Use --verbose to list all.\n`);
+    }
+};
+const writeIfNeeded = async (filePath, content, force) => {
+    try {
+        await fs.writeFile(filePath, content, { encoding: "utf8", flag: force ? "w" : "wx" });
+        return "written";
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return "exists";
+        throw error;
+    }
+};
+const commandRun = async (command, flags) => {
+    const task = runTask(command, flags);
     const dossierPath = flagString(flags, "dossier");
     if (!task && !dossierPath)
-        throw new Error("--task or --dossier is required.");
-    let payload = await createRun(client, {
-        cwd: cwd(),
-        cliVersion: version,
-        task,
-        dossierPath,
-        include: flagList(flags, "include"),
-        externalRunId: flagString(flags, "external-run-id") || undefined,
-        workloadId: flagString(flags, "workload-id", defaultWorkloadId),
-        retentionTtlSeconds: flagNumber(flags, "retention-ttl-seconds", 86400)
-    });
+        throw new Error("--task, positional task, or --dossier is required.");
+    validateWatchFlags(flags);
+    if (hasFlag(flags, "dry-run")) {
+        if (wantsWatch(flags))
+            throw new Error("--dry-run cannot be combined with --watch or --jsonl.");
+        if (dossierPath) {
+            const inspection = await inspectDossierFile(path.resolve(cwd(), dossierPath));
+            if (hasFlag(flags, "json"))
+                printSuccess("run.preview", inspection, localJsonContext(flags));
+            else
+                process.stdout.write(`Bundle has ${inspection.entries.length} entries\n`);
+            return;
+        }
+        const preview = await previewTaskDossier({ cwd: cwd(), include: flagList(flags, "include") });
+        if (hasFlag(flags, "json"))
+            printSuccess("run.preview", preview, localJsonContext(flags));
+        else
+            printPreview(preview, hasFlag(flags, "verbose"));
+        return;
+    }
+    const client = makeClient(flags);
+    const template = readTemplateSelection(flags);
+    let payload;
+    try {
+        payload = await createRun(client, {
+            cwd: cwd(),
+            cliVersion: version,
+            task,
+            dossierPath,
+            include: flagList(flags, "include"),
+            externalRunId: flagString(flags, "external-run-id") || undefined,
+            templateId: template.id,
+            retentionTtlSeconds: flagNumber(flags, "retention-ttl-seconds", 86400)
+        });
+    }
+    catch (error) {
+        throw runCreationError(error, client, template);
+    }
+    if (wantsWatch(flags)) {
+        const watched = await watchRunWithOutput(client, payload.run.id, flags, payload);
+        if (!watched)
+            return;
+        payload = watched;
+        if (!hasFlag(flags, "jsonl"))
+            printRun(payload);
+        if (isTerminalRun(payload.run) && payload.run.status !== "completed")
+            process.exitCode = 2;
+        return;
+    }
     if (hasFlag(flags, "wait")) {
         payload = await waitForRun(client, payload.run.id, {
             pollIntervalMs: flagNumber(flags, "poll-interval-ms", 2000),
             timeoutSeconds: flagNumber(flags, "timeout-seconds", 1800)
         });
     }
-    if (hasFlag(flags, "json"))
-        printJson(payload);
+    if (hasFlag(flags, "json")) {
+        printSuccess("run.create", {
+            ...publicRunPayload(payload),
+            selection: { template_id: template.id, source: template.source }
+        }, jsonContext(client));
+    }
     else
         printRun(payload);
     if (hasFlag(flags, "wait") && isTerminalRun(payload.run) && payload.run.status !== "completed")
@@ -82,21 +402,28 @@ const commandBatch = async (flags) => {
     if (!tasksPath)
         throw new Error("--tasks is required.");
     const client = makeClient(flags);
+    const template = readTemplateSelection(flags);
     const tasks = await readTasks(tasksPath);
     const batchId = flagString(flags, "batch-id") || await stableBatchId(tasksPath);
     const include = flagList(flags, "include");
     const maxParallel = flagNumber(flags, "max-parallel", 5);
     const wait = hasFlag(flags, "wait");
     const results = await runPool(tasks, maxParallel, async (task, index) => {
-        let payload = await createRun(client, {
-            cwd: cwd(),
-            cliVersion: version,
-            task: task.task,
-            include: task.include || include,
-            externalRunId: task.external_run_id || `sanbox-batch-${batchId}-${index + 1}`,
-            workloadId: flagString(flags, "workload-id", defaultWorkloadId),
-            retentionTtlSeconds: flagNumber(flags, "retention-ttl-seconds", 86400)
-        });
+        let payload;
+        try {
+            payload = await createRun(client, {
+                cwd: cwd(),
+                cliVersion: version,
+                task: task.task,
+                include: task.include || include,
+                externalRunId: task.external_run_id || `sanbox-batch-${batchId}-${index + 1}`,
+                templateId: template.id,
+                retentionTtlSeconds: flagNumber(flags, "retention-ttl-seconds", 86400)
+            });
+        }
+        catch (error) {
+            throw runCreationError(error, client, template);
+        }
         if (wait) {
             payload = await waitForRun(client, payload.run.id, {
                 pollIntervalMs: flagNumber(flags, "poll-interval-ms", 2000),
@@ -105,9 +432,14 @@ const commandBatch = async (flags) => {
         }
         return payload;
     });
-    const output = { batch_id: batchId, runs: results.map((result) => result.run), results };
+    const output = {
+        batch_id: batchId,
+        selection: { template_id: template.id, source: template.source },
+        runs: results.map((result) => publicRun(result.run)),
+        results: results.map(publicRunPayload)
+    };
     if (hasFlag(flags, "json"))
-        printJson(output);
+        printSuccess("batch.create", output, jsonContext(client));
     else
         results.forEach(printRun);
     if (wait && results.some((result) => result.run.status !== "completed"))
@@ -123,12 +455,227 @@ const commandAuthCheck = async (flags) => {
     const selected = organizations.find((item) => item.slug === org) || null;
     const output = { ok: Boolean(selected), org, selected, me };
     if (hasFlag(flags, "json"))
-        printJson(output);
+        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 commandContext = async (flags) => {
+    const client = makeClient(flags);
+    const selection = readTemplateSelection(flags, { required: false });
+    const [me, providerPayload, templatePayload] = await Promise.all([
+        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,
+        authentication: me.auth || null,
+        template_selection: selection
+            ? { id: selection.id, source: selection.source, found: Boolean(selectedTemplate), template: selectedTemplate }
+            : null,
+        model_providers: providerPayload.providers,
+        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(`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`);
+};
+const commandModelProviders = async (command, flags) => {
+    const client = makeClient(flags);
+    const action = command[1];
+    if (action === "list") {
+        const payload = await client.listModelProviders();
+        if (hasFlag(flags, "json")) {
+            printSuccess("model_providers.list", payload, jsonContext(client));
+            return;
+        }
+        for (const provider of payload.providers) {
+            const id = providerId(provider);
+            process.stdout.write(`${id}${provider.status ? ` ${provider.status}` : ""}${provider.configured === undefined ? "" : ` configured=${provider.configured}`}\n`);
+        }
+        return;
+    }
+    if (action === "get") {
+        const id = requiredPositional(command[2], "model_provider_required", "model-providers get requires a provider id.");
+        let payload;
+        try {
+            payload = await client.getModelProvider(id);
+        }
+        catch (error) {
+            if (error instanceof SanboxApiError) {
+                throw new CliError("model_provider_not_found", error.message, {
+                    status: error.status,
+                    details: { provider_id: id },
+                    nextActions: [commandAction(["sanbox", "model-providers", "list", "--json"], "List supported providers and their organization-scoped status.")]
+                });
+            }
+            throw error;
+        }
+        const nextActions = payload.provider.configured === false ? [providerConsoleAction(client)] : [];
+        if (hasFlag(flags, "json")) {
+            printSuccess("model_providers.get", payload, jsonContext(client), nextActions);
+            return;
+        }
+        process.stdout.write(`${providerId(payload.provider)}${payload.provider.status ? ` ${payload.provider.status}` : ""}\n`);
+        return;
+    }
+    if (action === "models") {
+        const id = requiredPositional(command[2], "model_provider_required", "model-providers models requires a provider id.");
+        let payload;
+        try {
+            payload = await client.listProviderModels(id);
+        }
+        catch (error) {
+            if (error instanceof SanboxApiError) {
+                throw new CliError("model_provider_unavailable", error.message, {
+                    status: error.status,
+                    details: { provider_id: id },
+                    nextActions: [
+                        commandAction(["sanbox", "model-providers", "get", id, "--json"], "Inspect the provider's organization-scoped status."),
+                        providerConsoleAction(client)
+                    ]
+                });
+            }
+            throw error;
+        }
+        if (hasFlag(flags, "json")) {
+            printSuccess("model_providers.models", payload, jsonContext(client));
+            return;
+        }
+        for (const model of payload.models) {
+            const modelId = String(model.model_id || model.id || "");
+            const displayName = String(model.display_name || model.name || "");
+            process.stdout.write(`${modelId}${displayName && displayName !== modelId ? `\t${displayName}` : ""}${model.selectable === undefined ? "" : `\tselectable=${model.selectable}`}\n`);
+        }
+        return;
+    }
+    throw new CliError("model_providers_action_required", "model-providers requires an action: list, get, or models.");
+};
+const commandTemplates = async (command, flags) => {
+    const client = makeClient(flags);
+    const action = command[1];
+    if (action === "list") {
+        const payload = await client.listTemplates();
+        const nextActions = payload.templates.length === 0
+            ? [
+                commandAction(["sanbox", "context", "--json"], "Inspect the selected organization and current authentication role."),
+                templateAdminConsoleAction(client)
+            ]
+            : [];
+        if (hasFlag(flags, "json")) {
+            printSuccess("templates.list", payload, jsonContext(client), nextActions);
+            return;
+        }
+        for (const template of payload.templates) {
+            process.stdout.write(`${template.id}\t${templateName(template)}\t${template.provider_id || ""}\t${template.model_id || ""}${template.runnable === undefined ? "" : `\trunnable=${template.runnable}`}\n`);
+        }
+        return;
+    }
+    if (action === "get") {
+        const id = requiredPositional(command[2], "template_id_required", "templates get requires a template id or slug.");
+        let payload;
+        try {
+            payload = await client.getTemplate(id);
+        }
+        catch (error) {
+            if (error instanceof SanboxApiError) {
+                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.")]
+                });
+            }
+            throw error;
+        }
+        if (hasFlag(flags, "json")) {
+            printSuccess("templates.get", payload, jsonContext(client), templateActions());
+            return;
+        }
+        process.stdout.write(`${payload.template.id} ${templateName(payload.template)} provider=${payload.template.provider_id || ""} model=${payload.template.model_id || ""}${payload.template.runnable === undefined ? "" : ` runnable=${payload.template.runnable}`}\n`);
+        return;
+    }
+    if (action === "validate") {
+        const id = requiredPositional(command[2], "template_id_required", "templates validate requires a template id or slug.");
+        let payload;
+        try {
+            payload = await client.validateTemplate(id);
+        }
+        catch (error) {
+            if (error instanceof SanboxApiError) {
+                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.")]
+                });
+            }
+            throw error;
+        }
+        const runnable = validationRunnable(payload);
+        const nextActions = runnable ? [] : [
+            commandAction(["sanbox", "model-providers", "list", "--json"], "Inspect model-provider configuration for this organization."),
+            providerConsoleAction(client)
+        ];
+        if (hasFlag(flags, "json")) {
+            printSuccess("templates.validate", payload, jsonContext(client), nextActions);
+            return;
+        }
+        process.stdout.write(`${runnable ? "ready" : "blocked"} template=${id}\n`);
+        return;
+    }
+    if (action === "create") {
+        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.");
+        let payload;
+        try {
+            payload = await client.createTemplate({
+                name,
+                provider_id: modelProvider,
+                model_id: model,
+                web_access: hasFlag(flags, "web-access")
+            });
+        }
+        catch (error) {
+            throw templateCreationError(error, client, modelProvider, model);
+        }
+        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.")
+            ]);
+            return;
+        }
+        process.stdout.write(`created ${payload.template.id} provider=${payload.template.provider_id || modelProvider} model=${payload.template.model_id || model}\n`);
+        return;
+    }
+    throw new CliError("templates_action_required", "templates requires an action: list, get, validate, or create.");
+};
 const commandRuns = async (command, flags) => {
     const client = makeClient(flags);
     const action = command[1];
@@ -138,7 +685,7 @@ const commandRuns = async (command, flags) => {
     if (action === "get") {
         const payload = await client.getRun(runId);
         if (hasFlag(flags, "json"))
-            printJson(payload);
+            printSuccess("runs.get", publicRunPayload(payload), jsonContext(client));
         else
             printRun(payload);
         return;
@@ -146,15 +693,26 @@ const commandRuns = async (command, flags) => {
     if (action === "events") {
         const payload = await client.listEvents(runId, flagNumber(flags, "after-event-id", 0));
         if (hasFlag(flags, "json"))
-            printJson(payload);
+            printSuccess("runs.events", payload, jsonContext(client));
         else
             payload.events.forEach((event) => process.stdout.write(`${event.id} ${event.level} ${event.kind} ${event.message}\n`));
         return;
     }
+    if (action === "watch") {
+        validateWatchFlags({ ...flags, watch: true });
+        const payload = await watchRunWithOutput(client, runId, { ...flags, watch: true });
+        if (!payload)
+            return;
+        if (!hasFlag(flags, "jsonl"))
+            printRun(payload);
+        if (isTerminalRun(payload.run) && payload.run.status !== "completed")
+            process.exitCode = 2;
+        return;
+    }
     if (action === "cancel") {
         const payload = await client.cancelRun(runId);
         if (hasFlag(flags, "json"))
-            printJson(payload);
+            printSuccess("runs.cancel", publicRunPayload(payload), jsonContext(client));
         else
             printRun(payload);
         return;
@@ -165,44 +723,294 @@ const commandRuns = async (command, flags) => {
             throw new Error("--message is required.");
         const payload = await client.sendMessage(runId, message);
         if (hasFlag(flags, "json"))
-            printJson(payload);
+            printSuccess("runs.message", publicRunPayload(payload), jsonContext(client));
         else
             printRun(payload);
         return;
     }
     throw new Error(`Unknown runs action: ${action}`);
 };
+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 });
+    const checks = [];
+    const nextActions = [];
+    const add = (name, ok, detail, data) => checks.push({
+        name,
+        ok,
+        detail,
+        ...(data === undefined ? {} : { data })
+    });
+    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>" }));
+    }
+    try {
+        const res = await fetch(`${apiUrl}/health`);
+        add("api_health", res.ok, `${res.status} ${res.statusText}`);
+    }
+    catch (error) {
+        add("api_health", false, error instanceof Error ? error.message : String(error));
+    }
+    if (org && apiKey) {
+        const client = new SanboxClient({ apiUrl, org, apiKey });
+        try {
+            const me = await client.me();
+            const organizations = Array.isArray(me.organizations)
+                ? me.organizations
+                : [];
+            add("auth", true, "authenticated");
+            add("org_visible", organizations.some((item) => item.slug === org), org);
+        }
+        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 {
+            try {
+                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", false, error instanceof Error ? error.message : String(error));
+                nextActions.push(...templateActions());
+            }
+        }
+    }
+    try {
+        const preview = await previewTaskDossier({ cwd: cwd(), include: ["README.md"] });
+        add("bundle_preview", true, `${preview.files.length} file(s), ${formatBytes(preview.totalBytes)}`);
+    }
+    catch (error) {
+        add("bundle_preview", false, error instanceof Error ? error.message : String(error));
+    }
+    const output = {
+        ok: checks.every((check) => check.ok),
+        template_selection: selection,
+        checks
+    };
+    if (hasFlag(flags, "json")) {
+        printSuccess("doctor", output, { api_url: apiUrl, ...(org ? { org } : {}) }, nextActions);
+    }
+    else {
+        for (const check of checks) {
+            process.stdout.write(`${check.ok ? "ok" : "fail"} ${check.name}: ${check.detail}\n`);
+        }
+    }
+    if (!output.ok)
+        process.exitCode = 2;
+};
+const commandBundle = async (command, flags) => {
+    const action = command[1];
+    if (action === "preview") {
+        const preview = await previewTaskDossier({ cwd: cwd(), include: flagList(flags, "include") });
+        if (hasFlag(flags, "json"))
+            printSuccess("bundle.preview", preview, localJsonContext(flags));
+        else
+            printPreview(preview, hasFlag(flags, "verbose"));
+        return;
+    }
+    if (action === "create") {
+        const task = bundleTask(command, flags);
+        const outPath = flagString(flags, "out");
+        if (!task)
+            throw new Error("bundle create requires a positional task or --task.");
+        if (!outPath)
+            throw new Error("bundle create requires --out.");
+        const dossier = await writeTaskDossier({
+            cwd: cwd(),
+            task,
+            include: flagList(flags, "include"),
+            cliVersion: version,
+            outPath: path.resolve(cwd(), outPath)
+        });
+        const output = { path: outPath, sha256: dossier.sha256, files: dossier.files, bytes: dossier.buffer.byteLength };
+        if (hasFlag(flags, "json"))
+            printSuccess("bundle.create", output, localJsonContext(flags));
+        else
+            process.stdout.write(`Wrote ${outPath} with ${dossier.files.length} files (${formatBytes(dossier.buffer.byteLength)})\n`);
+        return;
+    }
+    if (action === "inspect") {
+        const bundlePath = command[2] || flagString(flags, "dossier") || flagString(flags, "bundle");
+        if (!bundlePath)
+            throw new Error("bundle inspect requires a ZIP path.");
+        const inspection = await inspectDossierFile(path.resolve(cwd(), bundlePath));
+        if (hasFlag(flags, "json")) {
+            printSuccess("bundle.inspect", inspection, localJsonContext(flags));
+            return;
+        }
+        process.stdout.write(`Entries: ${inspection.entries.length}\n`);
+        if (inspection.manifest)
+            process.stdout.write("manifest.json: present\n");
+        if (inspection.runbook)
+            process.stdout.write(`RUNBOOK.md: ${inspection.runbook.split(/\r?\n/)[0] || "present"}\n`);
+        return;
+    }
+    throw new Error("bundle requires action: preview, create, or inspect.");
+};
 const commandInit = async (command, flags) => {
-    if (command[1] !== "agent")
-        throw new Error("Only `sanbox init agent` is supported.");
-    if (hasFlag(flags, "write")) {
-        const dir = path.join(cwd(), ".sanbox");
-        await fs.mkdir(dir, { recursive: true });
-        await fs.writeFile(path.join(dir, "agent.md"), agentInstructions, "utf8");
-        process.stdout.write(".sanbox/agent.md written\n");
+    const dir = path.join(cwd(), ".sanbox");
+    if (command[1] === "agent") {
+        if (hasFlag(flags, "write")) {
+            await fs.mkdir(dir, { recursive: true });
+            await fs.writeFile(path.join(dir, "agent.md"), agentInstructions, "utf8");
+            if (hasFlag(flags, "json")) {
+                printSuccess("init.agent", { path: ".sanbox/agent.md", status: "written" }, localJsonContext(flags));
+            }
+            else {
+                process.stdout.write(".sanbox/agent.md written\n");
+            }
+            return;
+        }
+        if (hasFlag(flags, "json")) {
+            printSuccess("init.agent", { instructions: agentInstructions }, localJsonContext(flags));
+        }
+        else {
+            process.stdout.write(agentInstructions);
+        }
         return;
     }
-    process.stdout.write(agentInstructions);
+    if (command[1])
+        throw new Error("init supports no subcommand or `agent`.");
+    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 = [
+        "# Project-specific Sanbox excludes. Defaults already exclude .git, node_modules, build output, env files, and secret-like names.",
+        "",
+        "# examples:",
+        "# data/private/**",
+        "# tmp/**",
+        ""
+    ].join("\n");
+    await fs.mkdir(dir, { recursive: true });
+    const results = [
+        [".sanbox/config.json", await writeIfNeeded(path.join(dir, "config.json"), `${JSON.stringify(config, null, 2)}\n`, force)],
+        [".sanbox/agent.md", await writeIfNeeded(path.join(dir, "agent.md"), agentInstructions, force)],
+        [".sanboxignore", await writeIfNeeded(path.join(cwd(), ".sanboxignore"), sanboxIgnore, force)]
+    ];
+    if (hasFlag(flags, "json")) {
+        printSuccess("init", {
+            files: results.map(([file, status]) => ({ file, status })),
+            template_selection: template
+        }, { api_url: apiUrl, ...(org ? { org } : {}) }, template ? [] : templateActions());
+    }
+    else {
+        for (const [file, status] of results)
+            process.stdout.write(`${status} ${file}\n`);
+    }
 };
-const main = async () => {
-    const { command, flags } = parseArgs(process.argv.slice(2));
-    if (command.length === 0 || hasFlag(flags, "help")) {
+const helpFor = (command) => {
+    if (command[0] === "run")
+        return runHelp;
+    if (command[0] === "bundle")
+        return bundleHelp;
+    if (command[0] === "doctor")
+        return doctorHelp;
+    if (command[0] === "model-providers")
+        return modelProvidersHelp;
+    if (command[0] === "templates")
+        return templatesHelp;
+    return help;
+};
+const commandId = (command) => {
+    if (command[0] === "auth")
+        return "auth.check";
+    if (command[0] === "context")
+        return "context.get";
+    if (command[0] === "model-providers")
+        return `model_providers.${command[1] || "unknown"}`;
+    if (command[0] === "templates")
+        return `templates.${command[1] || "unknown"}`;
+    if (command[0] === "run")
+        return "run.create";
+    if (command[0] === "batch")
+        return "batch.create";
+    if (command[0] === "bundle")
+        return `bundle.${command[1] || "unknown"}`;
+    if (command[0] === "runs")
+        return `runs.${command[1] || "unknown"}`;
+    return command[0] || "help";
+};
+const main = async (command, flags) => {
+    if (command.length === 0) {
         process.stdout.write(help);
         return;
     }
+    if (hasFlag(flags, "help")) {
+        process.stdout.write(helpFor(command));
+        return;
+    }
     if (command[0] === "auth" && command[1] === "check")
         return commandAuthCheck(flags);
+    if (command[0] === "context")
+        return commandContext(flags);
+    if (command[0] === "doctor")
+        return commandDoctor(flags);
+    if (command[0] === "model-providers")
+        return commandModelProviders(command, flags);
+    if (command[0] === "templates")
+        return commandTemplates(command, flags);
     if (command[0] === "run")
-        return commandRun(flags);
+        return commandRun(command, flags);
     if (command[0] === "batch")
         return commandBatch(flags);
+    if (command[0] === "bundle")
+        return commandBundle(command, flags);
     if (command[0] === "runs")
         return commandRuns(command, flags);
     if (command[0] === "init")
         return commandInit(command, flags);
-    throw new Error(`Unknown command: ${command.join(" ")}`);
+    throw new CliError("unknown_command", `Unknown command: ${command.join(" ")}`);
 };
-main().catch((error) => {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-    process.exit(1);
+const parsed = parseArgs(process.argv.slice(2));
+main(parsed.command, parsed.flags).catch((error) => {
+    if (hasFlag(parsed.flags, "jsonl")) {
+        printJsonlError(commandId(parsed.command), error, localJsonContext(parsed.flags));
+    }
+    else if (hasFlag(parsed.flags, "json")) {
+        printError(commandId(parsed.command), error, localJsonContext(parsed.flags));
+    }
+    else {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    process.exitCode = error instanceof CliError ? error.exitCode : 1;
 });