@tangle-network/sandbox-cli 0.14.0-develop.20260727215658.53efef5 → 0.14.1

package/README.md

@@ -52,6 +52,12 @@ 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:
@@ -63,8 +69,14 @@ Three flows are supported:
 Credential lookup precedence:
 
 1. `--api-key` flag
-2. `TANGLE_API_KEY` environment variable
-3. `~/.tangle/credentials` (populated by `tangle auth login`)
+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:
 
@@ -77,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:

package/SKILL.md

@@ -12,7 +12,12 @@ 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 |
 |----------|--------|--------|
@@ -20,14 +25,18 @@ Generic command auth modes, resolved in order:
 | 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` |
-| 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 authentication is needed.
@@ -257,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
@@ -277,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