@tangle-network/sandbox-cli 0.12.2-develop.20260726033513.aa4b682 → 0.12.6

package/README.md

@@ -30,7 +30,9 @@ npx @tangle-network/sandbox-cli sandbox list
 npx tangle-sandbox --help
 ```
 
-Never run bare `npx tangle` (or `npx tangle-cli`) — those npm names belong to unrelated third-party packages and would execute someone else's code. The official names are `@tangle-network/sandbox-cli` and its forwarding alias `tangle-sandbox`.
+Never run bare `npx tangle` (or `npx tangle-cli`).
+Those npm names belong to unrelated third-party packages and would execute someone else's code.
+The official names are `@tangle-network/sandbox-cli` and its forwarding alias `tangle-sandbox`.
 
 Install globally to expose the short `tangle` binary on PATH:
 
@@ -50,21 +52,32 @@ pnpm --filter @tangle-network/sandbox-cli build
 node products/sandbox/cli/bin/tangle.js --help
 ```
 
+## Supervisor accounting
+
+`tangle supervise` reports measured tokens and cost for successful and failed runs.
+A run without a winner can still incur cost.
+Unknown totals display as `Unavailable` and appear as `null` in JSON output.
+
 ## Authentication
 
 Three flows are supported:
 
 - **Browser login** (default): `tangle auth login` opens a browser to complete OAuth with `github`, `google`, or `microsoft` identity providers.
 - **Device code**: `tangle auth login --no-browser` for headless environments.
-- **API key**: `tangle auth login --api-key sk-tan-...` (or set `TANGLE_API_KEY`; `SANDBOX_API_KEY` accepted as deprecated alias).
+- **API key**: `tangle auth login --api-key sk-tan-...` (or set `TANGLE_API_KEY`).
 
 Credential lookup precedence:
 
 1. `--api-key` flag
-2. `TANGLE_API_KEY` environment variable (preferred)
-3. `SANDBOX_API_KEY` environment variable (deprecated alias, accepted for backwards compatibility)
+2. `TANGLE_API_KEY_FILE` managed credential file
+3. `TANGLE_API_KEY` environment variable
 4. `~/.tangle/credentials` (populated by `tangle auth login`)
 
+The sidecar publishes refreshed delegated credentials through `TANGLE_API_KEY_FILE`.
+The CLI reads this file for each request, including requests from an existing client.
+A configured file that is missing, unreadable, or malformed fails without falling back to an older key.
+A verified Sandbox request can install a new source credential; an expired source cannot renew itself unattended.
+
 Common commands:
 
 ```bash
@@ -76,6 +89,50 @@ tangle auth profiles
 
 `tangle auth login` validates the supplied credential against `/v1/account/me`, which requires a valid token.
 
+### The two surfaces
+
+Commands address one of two services, and the two accept different credentials.
+
+| Surface | Command families | Credential |
+|---|---|---|
+| Sandbox API | `sandbox`, `exec`, `ssh`, `fs`, `process`, `snapshot`, `secret`, `agent`, `fleet`, `batch`, `usage` | the session `tangle auth login` stores, or an `sk-tan-*` key |
+| Platform control plane (`id.tangle.tools`) | `keys`, `workflows`, `hub` | an `sk-tan-*` key only |
+
+The platform does not accept the sandbox session: it belongs to a different
+audience. After a browser login the CLI therefore mints a short-lived platform
+key from that session on the first platform command, caches it in the same
+credential store, and replaces it before it expires. Nothing durable is written
+for a surface you never use, and no long-lived key sits on disk.
+
+An `sk-tan-*` key is used exactly as supplied on both surfaces, whether it
+arrives through `--api-key`, `TANGLE_API_KEY`, or `tangle auth login --api-key`,
+so a spawned sandbox and a CI job keep the credential they were given and no
+mint replaces it. `TANGLE_HUB_CAPABILITY_TOKEN` serves the `hub` commands only.
+
+### What the minted credential may do
+
+The minted key lives for minutes, so the platform refuses key creation and
+revocation through it: a credential that short must not add or destroy authority
+that outlasts it.
+
+- `tangle keys list` works after `tangle auth login`.
+- `tangle keys create` and `tangle keys revoke` need a key you minted yourself:
+  set `TANGLE_API_KEY`, run `tangle auth login --api-key sk-tan-…`, or mint the
+  key in the web console.
+
+Everything else on the control plane — `tangle workflows`, `tangle hub` — works
+from the login alone.
+
+`tangle auth status` reports both surfaces. It exits non-zero when either one
+REFUSES the stored credential — a behaviour change for a script that gated on
+the old sandbox-only check, and the point of it: the platform rejecting the
+credential used to be reported as success. An unreachable platform is a
+different answer and exits zero, because an outage says nothing about the
+credential; read `platform.reachable` in `--json` to gate platform work.
+`--base-url` names the sandbox host for BOTH halves: the session is checked
+there, and the platform credential is minted there, so the two lines of the
+answer always describe one deployment.
+
 ## Command Surface
 
 Top-level command groups:
@@ -91,6 +148,7 @@ Top-level command groups:
 - `usage`
 - `permissions`
 - `backend`
+- `batch`
 - `process`
 - `fs`
 
@@ -101,7 +159,7 @@ Examples:
 tangle auth login --api-key sk_...
 
 # sandbox lifecycle
-tangle sandbox create --name my-box --image node:20 --ssh
+tangle sandbox create --name my-box --environment node:20 --ssh
 tangle sandbox list
 tangle sandbox get sbx_123
 tangle sandbox stop sbx_123
@@ -112,14 +170,14 @@ tangle sandbox delete sbx_123
 tangle exec sbx_123 "npm test"
 tangle ssh sbx_123
 tangle agent prompt sbx_123 "Summarize this repo"
-tangle agent task sbx_123 "Fix the failing tests"
+tangle agent prompt sbx_123 "Fix the failing tests"
 tangle fleet create --count 4 --coordinator
 
 # grant hub connections to the agent (see hub-reference.md for the 3 modes).
 # the connection is an id or a provider name (resolved via `tangle hub connections`).
-tangle agent task sbx_123 "triage issues" \
+tangle agent prompt sbx_123 "triage issues" \
   --connection github:github.issues.search,github.issues.create
-tangle agent task sbx_123 "file the report" --connection github:* --allow-writes
+tangle agent prompt sbx_123 "file the report" --connection github:* --allow-writes
 
 # temporary GPU for an eval; omitted provider picks the cheapest configured cloud
 tangle sandbox gpu run sbx_123 \
@@ -138,7 +196,7 @@ tangle fs ls sbx_123 /workspace
 ```
 
 Hub commands (`tangle hub …`) and `tangle agent --connection` auto-mint a
-short-lived platform Hub key from your `tangle auth login` session — no separate
+short-lived platform Hub key from your `tangle auth login` session, with no separate
 key needed. See [`hub-reference.md`](./hub-reference.md) for the `--connection`
 grant modes, `--allow-writes`, and `permissions revert-writes`.
 
@@ -188,14 +246,40 @@ tangle sandbox create --name gpu-eval \
 The final detach output includes billed seconds and customer cost.
 Use `tangle usage` to inspect account-level GPU seconds and GPU spend.
 
+## Batch Runs
+
+Run each task against one explicitly named backend:
+
+```bash
+tangle batch run --tasks tasks.json --backend primary=opencode
+```
+
+`tasks.json` is an array of `{ "id": "...", "message": "..." }` objects or an object with a `tasks` array.
+At least one `--backend <id=type>` is required with `--tasks` or `--task`.
+
+Repeat `--backend <id=type>` to run every task against multiple backends:
+
+```bash
+tangle batch run --tasks tasks.json \
+  --backend writer=opencode \
+  --backend reviewer=claude-code \
+  --stream
+```
+
+Backend IDs must be unique and use 1 to 128 letters, numbers, dots, underscores, or hyphens.
+Use `--model provider/model` only when one backend is selected.
+Each result is identified by both `taskId` and `backendId`.
+JSON output reports `totalTasks`, `totalBackends`, `totalExecutions`, `totalSuccess`, `totalFailure`, `totalRetries`, and `successRate`.
+
+Use `--request <file.json>` when each backend needs its own model, profile, server, or lifecycle configuration.
+The file uses the same complete request shape as the TypeScript SDK and cannot be combined with inline task or backend flags.
+
 ## Provisioning Coverage
 
-`tangle sandbox create` exposes the full SDK provisioning surface, including image/environment, resources (CPU, memory, disk), temporary GPU leases, lifetime and idle timeout, driver and backend selection (`opencode`, `claude-code`, `codex`, `cursor`, `amp`, and other registry backends), SSH and web terminal, env and secret injection, metadata, initial permissions, git clone, tool pre-install, BYOS3 storage, snapshot restore, and outbound network controls. Run `tangle sandbox create --help` for the canonical flag list.
+`tangle sandbox create` supports environments or container images, resources, temporary GPU leases, lifecycle limits, driver and backend selection, SSH and web terminal, environment variables, secrets, metadata, git clone, BYOS3 storage, and snapshot restore.
+Use the `tools`, `permissions`, `network`, and `expose` commands after creation.
+Run `tangle sandbox create --help` for the current flag list.
 
 ## Limitations
 
 - `snapshot restore` creates a new sandbox from a snapshot; the command signature suggests in-place restore.
-
-## Design Follow-Up
-
-For the architecture review, parity checklist, and auth flow spec, see [CHECKLIST.md](./CHECKLIST.md).

package/SKILL.md

@@ -1,34 +1,45 @@
 ---
 name: tangle-cli
-description: Use when interacting with Tangle sandboxes, executing hub tools, managing agent tasks, operating on sandbox filesystems, building workflows, connecting to external providers, or setting up integrations and automations from a terminal. Triggers include tangle, tangle sandbox, tangle hub, tangle agent, tangle exec, tangle fs, tangle snapshot, tangle secret, tangle workflows, tangle hub connect, github, slack, google, microsoft, external connections, provider integrations, hub tools, or any tangle command.
+description: Use Tangle Sandbox CLI for lifecycle, prompts, files, fleets, Hub tools, and integrations.
 ---
 
 # Tangle CLI
 
 ## Overview
 
-`tangle` is the CLI for Tangle Sandbox operations — create sandboxes, run agents, execute hub tools, manage files, secrets, snapshots, git, and more. All commands support `--help` for inline reference.
+`tangle` is the CLI for Tangle Sandbox operations: create sandboxes, run agents, execute hub tools, and manage files, secrets, snapshots, and git.
+All commands support `--help` for inline reference.
 
 ## Auth
 
-Generic command auth modes, resolved in order:
+Commands address one of two services. Sandbox commands (`sandbox`, `exec`,
+`ssh`, `fs`, `snapshot`, `secret`, `agent`, …) address the sandbox API. Platform
+commands (`keys`, `workflows`, `hub`) address the control plane at
+`id.tangle.tools`, which accepts only an `sk-tan-*` key.
+
+Sandbox command auth modes, resolved in order:
 
 | Priority | Source | Set via |
 |----------|--------|--------|
 | 1 | CLI flag | `--api-key <key>` |
-| 2 | Env var | `TANGLE_API_KEY` or `SANDBOX_API_KEY` |
+| 2 | Env var | `TANGLE_API_KEY` |
 | 3 | Profile store | `tangle auth login` (keychain or file) |
 
-Hub commands resolve auth in this order:
+Platform commands resolve auth in the same order, with one step added: the
+session that `tangle auth login` stores is not a platform credential, so the CLI
+mints a short-lived platform key from it on first use and refreshes it as
+needed. Hub commands also accept `TANGLE_HUB_CAPABILITY_TOKEN`, ranked directly
+below `--api-key`; other platform commands do not, because that token
+authenticates `/v1/hub/exec` alone.
 
-| Priority | Source | Set via |
-|----------|--------|--------|
-| 1 | CLI flag | `--api-key <key>` |
-| 2 | Hub capability | `TANGLE_HUB_CAPABILITY_TOKEN` |
-| 3 | Env var | `TANGLE_API_KEY` or `SANDBOX_API_KEY` |
-| 4 | Profile store | `tangle auth login` (keychain or file) |
+The minted key lives for minutes, so the platform refuses key creation and
+revocation through it. `tangle keys list` works from a browser login; `tangle
+keys create` and `tangle keys revoke` need a key you minted yourself
+(`TANGLE_API_KEY`, `tangle auth login --api-key`, or the web console). A stored
+`sk-tan-*` is presented as-is and never minted over.
 
-**Inside a sandbox:** `tangle` is automatically authenticated. No extra auth needed — commands work out of the box.
+**Inside a sandbox:** `tangle` is automatically authenticated.
+No extra authentication is needed.
 
 ```bash
 # Browser login (preferred)
@@ -48,7 +59,7 @@ tangle auth login --profile work
 tangle auth profiles use work
 ```
 
-For hub env auth, set **exactly one** of `TANGLE_API_KEY`/`SANDBOX_API_KEY` or `TANGLE_HUB_CAPABILITY_TOKEN`.
+For hub env auth, set **exactly one** of `TANGLE_API_KEY` or `TANGLE_HUB_CAPABILITY_TOKEN`.
 
 ## Sandbox Lifecycle
 
@@ -105,7 +116,7 @@ tangle fleet create --count 4 \
   --gpu-idle-timeout 120
 ```
 
-## Hub — Full Workflow
+## Full Hub Workflow
 
 Hub lets agents use connected provider tools (GitHub, etc.) through Tangle without seeing provider OAuth tokens.
 
@@ -141,7 +152,7 @@ tangle hub tools describe github.issues.search --json
 
 ### Tool Execution
 
-Two equivalent commands — `call` and `exec`:
+Two equivalent commands are available: `call` and `exec`.
 
 ```bash
 # Basic call: <path tokens...> <json-input>
@@ -154,7 +165,8 @@ tangle hub call github issues createIssue '{"owner":"foo","repo":"bar","title":"
 
 ### Policy & Approvals
 
-Tools default to `ask` policy — they pause and require approval on first use.
+Tools default to the `ask` policy.
+They pause and require approval on first use.
 
 ```bash
 # List pending approvals
@@ -210,20 +222,14 @@ tangle secret update DATABASE_URL "new-value"
 tangle secret delete DATABASE_URL
 ```
 
-## Snapshots & Checkpoints
+## Snapshots
 
 ```bash
-# Snapshots (point-in-time for cloning/restoring)
 tangle snapshot create <sandbox-id>
 tangle snapshot list <sandbox-id>
 tangle snapshot restore <sandbox-id> <snapshot-id>   # creates new sandbox
 tangle snapshot revert <sandbox-id> <snapshot-id>    # reverts in-place
 tangle snapshot delete <sandbox-id> <snapshot-id>
-
-# Checkpoints (lightweight, local)
-tangle checkpoint create <id>
-tangle checkpoint list|ls <id>
-tangle checkpoint delete|rm <id> <checkpoint-id>
 ```
 
 ## Templates
@@ -260,19 +266,40 @@ tangle team invitations [team]  # List pending/historical invitations
 ## Workflows
 
 Authenticate with the `sk-tan-*` API key (`TANGLE_API_KEY`), same as the other
-platform commands — not a hub capability token.
+platform commands, not a hub capability token. These commands address the
+platform control plane, not the sandbox API. The host resolves from
+`--base-url`, then `TANGLE_HUB_URL` (which a spawned sandbox injects to name
+its own hub, so it wins over an ambient value), then `TANGLE_PLATFORM_URL`,
+then `https://id.tangle.tools`. On `workflows`,
+`--base-url` names the PLATFORM host — unlike `tangle keys`, where `--base-url`
+is the sandbox API and `--platform-url` is the platform.
+
+Authoring a workflow (graph topology, guards, joins, KV state, decisions):
+https://sandbox.tangle.tools/docs/workflows
 
 ```bash
 tangle workflows validate workflow.yml
 tangle workflows schema              # print JSON Schema
 tangle workflows create workflow.yml
+tangle workflows apply workflow.yml  # create or update, matched by the definition's name
 tangle workflows list
+tangle workflows fleet               # run tallies over a trailing window, failing first
 tangle workflows get <id>
 tangle workflows update <id> workflow.yml
 tangle workflows enable <id>
 tangle workflows disable <id>
 tangle workflows delete <id>
 
+# Templates
+tangle workflows templates                                   # starter gallery
+tangle workflows init <template-id>                          # instantiate, print YAML
+tangle workflows init <template-id> --param repo=o/r --file workflow.yml
+
+# Revisions
+tangle workflows revisions <id>          # definition history
+tangle workflows revision <id> <rev>     # one revision's YAML
+tangle workflows rollback <id> <rev>     # restore a rev as the new head
+
 # Runs
 tangle workflows run <id>                                   # trigger a run
 tangle workflows run <id> --input pull_request.number=123   # with trigger inputs
@@ -280,6 +307,23 @@ tangle workflows run <id> --wait                            # wait + print resul
 tangle workflows runs <id>                                  # run history
 tangle workflows run-detail <id> <runId>                    # single-run detail
 tangle workflows events <id> <runId>                        # tail live progress
+tangle workflows cancel <id> <runId>                        # cancel a queued/running run
+tangle workflows retry <id> <runId>                         # re-run a failed run with the same trigger context
+
+# Cross-run KV state
+tangle workflows kv list <id>
+tangle workflows kv get <id> <key>
+tangle workflows kv set <id> <key> '{"cursor":123}'
+tangle workflows kv set <id> <key> '{"cursor":123}' --cas 4   # compare-and-swap
+tangle workflows kv delete <id> <key>
+
+# Run artifacts
+tangle workflows artifacts <id> <runId>
+tangle workflows artifact-download <id> <runId> <artifactId> --out report.json
+
+# Human decisions
+tangle workflows decisions <id>                              # pending approvals
+tangle workflows decision-resolve <id> <runId> --choice deploy
 ```
 
 ## Other Commands
@@ -308,6 +352,7 @@ tangle tools install <id> python 3.12
 
 # Batch tasks across sandboxes
 tangle batch run --tasks tasks.json
+tangle batch run --tasks tasks.json --backend writer=opencode --backend reviewer=claude-code --stream
 
 # Intelligence reports
 tangle intelligence sandbox <id>
@@ -337,22 +382,23 @@ tangle permissions add <sandboxId> --userId <userId> --role editor
 
 | Goal | Commands |
 |------|----------|
-| Spin up sandbox, run agent | `tangle sandbox create --name X` → `tangle agent task <id> "..."` |
+| Spin up sandbox, run agent | `tangle sandbox create --name X` → `tangle agent prompt <id> "..."` |
 | Connect GitHub, read issues | `tangle hub connect github` → `tangle hub tools search "issues" --provider github` → `tangle hub call github issues search '{"q":"repo:X/Y is:issue"}'` |
 | Push code from sandbox to GitHub | `tangle hub connect github` → `tangle git add <id> files` → `tangle git commit <id> -m "msg"` → `tangle git push <id>` |
 | Save and restore state | `tangle snapshot create <id>` → ...work... → `tangle snapshot revert <id> <snap-id>` |
 | Set secret for agent use | `tangle secret create GITHUB_TOKEN "..."` → agent reads via `process.env.GITHUB_TOKEN` |
 | Set hub permissions | `tangle hub permissions set --connection conn_xxx --action github.issues.createIssue --decision allow` |
-| Batch parallel agent tasks | `tangle batch run --tasks tasks.json` (array of `{sandboxId, message}`) |
+| Batch parallel agent prompts | `tangle batch run --tasks tasks.json --backend primary=opencode` (array of `{id, message}`) |
+| Compare backends on the same tasks | `tangle batch run --tasks tasks.json --backend writer=opencode --backend reviewer=claude-code --stream` |
 
 ## Common Mistakes
 
-- **Forgetting `--reveal` on `secret show`** — values are hidden by default for safety.
-- **Using API-key env and `TANGLE_HUB_CAPABILITY_TOKEN` together for hub** — set exactly one env auth source, or use `--api-key` to override both.
-- **Calling hub tools without `--approve` on first use** — use `--approve` or set policy to `allow` first.
-- **Missing `--json` flag when piping output** — many commands need explicit `--json` for machine-readable output.
-- **`tangle hub exec` vs `tangle exec`** — `hub exec` runs hub tools; `exec` runs shell commands in a sandbox.
-- **`hub resume` doesn't replay** — after `hub resume --accept`, rerun original `hub exec` with `--approve`.
+- **Forgetting `--reveal` on `secret show`:** values are hidden by default for safety.
+- **Using API-key env and `TANGLE_HUB_CAPABILITY_TOKEN` together for hub:** set exactly one env auth source, or use `--api-key` to override both.
+- **Calling hub tools without `--approve` on first use:** use `--approve` or set policy to `allow` first.
+- **Missing `--json` when piping output:** many commands need explicit `--json` for machine-readable output.
+- **`tangle hub exec` vs `tangle exec`:** `hub exec` runs hub tools; `exec` runs shell commands in a sandbox.
+- **`hub resume` does not replay:** after `hub resume --accept`, rerun the original `hub exec` with `--approve`.
 
 ## Token Safety