@tangle-network/sandbox-cli 0.22.0-develop.20260814044321.7b71e30 → 0.22.0

package/README.md

@@ -15,7 +15,7 @@ See [Limitations](#limitations) for open gaps.
 
 ## Install
 
-One-liner (requires Node 20+ on PATH):
+One-liner (installs the CLI and a private runtime selected from its [`engines` metadata](./package.json)):
 
 ```bash
 curl -fsSL https://sandbox.tangle.tools/install.sh | sh
@@ -52,6 +52,80 @@ pnpm --filter @tangle-network/sandbox-cli build
 node products/sandbox/cli/bin/tangle.js --help
 ```
 
+## Graph factories
+
+Save a graph in a repository's `.tangle/graphs/<name>.yaml` or in
+`~/.tangle/graphs/<name>.yaml`. Repository graphs take precedence. The packaged
+[`haiku-review.yaml`](./examples/haiku-review.yaml) contains a writer, an independent
+critic and a declared completion check.
+
+```bash
+tangle graph new "Write and independently judge a haiku" --name haiku-review
+tangle graph run haiku-review --dry-run
+tangle graph run haiku-review
+tangle --json graph run haiku-review --cloud
+tangle --json graph inspect <run-id>
+tangle graph run haiku-review --resume <run-id>
+```
+
+Graphs use the selected harness's native subscription login. Set `seat` in
+`~/.tangle/config.json` to keep a default; `--seat` overrides it for every node.
+A graph with no integration needs requires no Tangle login. Before starting
+agents, an interactive run connects missing needs in the browser and resumes
+the same run. It uses the existing Tangle login when authentication is needed.
+Validation, `--json` and noninteractive runs report missing providers with the
+exact `tangle hub connect <provider>` command. Ctrl-C cancels login, connection
+polling and pending Hub requests.
+
+Local graph gates accept `--param gate.<id>=<choice>` or ask in the terminal.
+Supplied choices are validated before execution and recorded with the run;
+resume preserves them and Runtime replays completed decisions. JSON and
+noninteractive runs require an explicit answer. The `gate.` prefix is reserved
+for these CLI controls.
+
+Progress goes to stderr; `--json` returns the result or the shared error contract
+on stdout. Local run journals live under `~/.tangle/runs/<run-id>`, and local graph history
+lives in `~/.tangle/graph-registry`. Unknown token and cost totals remain `null`.
+
+`--cloud` saves the same source through Hub Workflows and returns its run ID
+immediately. The Workflow API owns execution, retained evidence and recovery;
+closing the CLI leaves the cloud run running. `inspect` reads that same run and
+prints the shared workflow viewer URL outside JSON mode.
+
+`--resume` restores saved inputs and rejects changed source, parameters, seat
+settings or placement. A completed winner returns its retained result without
+new native effects. A healthy cloud run attaches by reading its current state;
+only the server decides whether interrupted work can recover. Failed or
+cancelled terminal runs refuse continuation.
+
+For a cited analysis of retained graph evidence, install the maintained Braid companion
+with `npm install --global @tangle-network/braid`, then use an existing canonical
+AgentProfile reference:
+
+```bash
+tangle graph analyze <run-id> --profile ./profiles/reviewer.json --dry-run
+tangle graph analyze <run-id> --profile ./profiles/reviewer.json
+```
+
+Here `--profile` selects the analysis agent, distinct from a Tangle account
+profile. Analysis uses the CLI-owned subscription-only Bridge. Braid owns its
+saved analysis and encrypted state; the result includes its state path. Missing
+native capture or usage remains explicitly unavailable.
+
+## 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.
+
+## Workflow inputs
+
+Use `tangle workflows run <id> --input-file ~/.tangle/params/code-fix.json --wait`
+to run a stored preset. The file is a flat JSON object of string values, such as
+`{"repo":"o/r","base":"develop","change":"fix the parser"}`. Repeatable
+`--input key=value` flags override matching file keys. Invalid files fail before
+authentication or run admission; `--json` errors include `code`, `cause`, and `fix`.
+
 ## Authentication
 
 Three flows are supported:
@@ -63,8 +137,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.json` (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 +157,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:
@@ -90,7 +214,6 @@ Top-level command groups:
 - `fleet`
 - `snapshot`
 - `usage`
-- `permissions`
 - `backend`
 - `batch`
 - `process`
@@ -220,10 +343,20 @@ The file uses the same complete request shape as the TypeScript SDK and cannot b
 
 ## Provisioning Coverage
 
-`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.
+`tangle sandbox create` supports environments or container images, resources, temporary GPU leases, lifecycle limits, runtime (`--runtime docker|firecracker`), driver and backend selection, SSH and web terminal, environment variables, secrets, metadata, git clone, BYOS3 storage, and snapshot restore.
+Use the `sandbox network` and `sandbox 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.
+
+## Compliance posture is not a flag
+
+No CLI command takes a `--compliance` / HIPAA / PHI option, by design: a
+caller-asserted flag could dodge the platform's observability gates or
+claim a protection it never granted. The platform derives the posture from
+the credential's verified attribution and pins it server-side. Reads
+(`sandbox list`, `sandbox get`) surface it as the read-only `compliance:
+{ hipaa: true }` echo field — absent means the platform made no claim, and
+`hipaa: false` never appears.

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tangle-cli
-description: Use Tangle Sandbox CLI for lifecycle, prompts, files, fleets, Hub tools, and integrations.
+description: Use Tangle Sandbox CLI for graph factories, sandbox lifecycle, prompts, files, fleets, Hub tools, and integrations.
 ---
 
 # Tangle CLI
@@ -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.
@@ -52,6 +61,34 @@ tangle auth profiles use work
 
 For hub env auth, set **exactly one** of `TANGLE_API_KEY` or `TANGLE_HUB_CAPABILITY_TOKEN`.
 
+## Graph factories
+
+Use the existing `graph` commands to build and run AgentGraphs. Keep one source
+file for local and cloud execution; `graph --help` owns command usage.
+
+```bash
+tangle graph new "Implement and independently review the change" --name reviewed-change
+tangle graph run reviewed-change --dry-run
+tangle graph run reviewed-change
+tangle --json graph run reviewed-change --cloud
+tangle --json graph inspect <run-id>
+tangle graph run reviewed-change --resume <run-id>
+```
+
+Cloud dispatch returns immediately and the Workflow API owns the same run after
+CLI disconnect. Resume preserves recorded source and execution settings. A
+completed winner replays retained output; running cloud work attaches by read,
+while the server decides recovery eligibility. Failed or cancelled terminal
+work refuses continuation. Read retained evidence before starting fresh work.
+
+`graph analyze <run-id> --profile <name|path>` sends the retained source to the
+maintained Braid companion. Install it through `npm install --global
+@tangle-network/braid`. This `--profile` selects a canonical analysis AgentProfile,
+not Tangle account credentials. Use `--dry-run` to inspect the bound analysis
+configuration without dispatch. The CLI supplies its subscription-only Bridge;
+Braid owns the saved analysis. Missing source, native capture or measured usage
+stays unavailable.
+
 ## Sandbox Lifecycle
 
 ```bash
@@ -75,6 +112,24 @@ Use a normal sandbox first, then attach a GPU only for the work that needs it.
 Omit `--provider` to use the cheapest configured GPU cloud.
 Always set a spend cap and lifetime.
 
+Check which GPU clouds work before attaching. `gpu providers` lists every supported provider with its state (`ready`, `credential-invalid`, `unverified`, `not-configured`, `disabled`), the orchestrator variables it needs, and a live price for the accelerator you name:
+
+```bash
+tangle sandbox gpu providers <sandbox-id> --accelerator-kind nvidia-h100
+```
+
+| Provider | `--provider` | Orchestrator variables |
+| --- | --- | --- |
+| RunPod | `runpod` | `RUNPOD_API_KEY` |
+| Vast.ai | `vast-ai` | `VAST_API_KEY` |
+| Lambda | `lambda-labs` | `LAMBDA_API_KEY` |
+| Modal | `modal` | `MODAL_TOKEN_ID`, `MODAL_TOKEN_SECRET` |
+
+TensorDock, Paperspace, AWS, GCP, Azure, Crusoe and Fluidstack are also supported; `gpu providers` prints the variables each needs.
+Setting a provider's variables enables it; `GPU_LEASE_PROVIDERS` only narrows the set.
+An attach with no usable provider fails with 503 `GPU_PROVIDER_NOT_CONFIGURED` naming the variables to set; a refused key shows as `credential-invalid` and is never selected.
+Modal offers T4, L4, A10G, L40S, A100, H100, H200 and B200, not consumer cards such as the RTX 3090.
+
 ```bash
 # One-shot eval: attach GPU, run command, always destroy the lease.
 tangle sandbox gpu run <sandbox-id> \
@@ -147,8 +202,8 @@ Two equivalent commands are available: `call` and `exec`.
 
 ```bash
 # Basic call: <path tokens...> <json-input>
-tangle hub call github issues search '{"q":"repo:tangle-network/agent-dev-container is:issue"}'
-tangle hub exec github.issues.search '{"q":"repo:tangle-network/agent-dev-container is:issue"}'
+tangle hub call github issues search '{"q":"repo:tangle-network/agent-container is:issue"}'
+tangle hub exec github.issues.search '{"q":"repo:tangle-network/agent-container is:issue"}'
 
 # With explicit connection
 tangle hub call github issues createIssue '{"owner":"foo","repo":"bar","title":"Fix bug"}' --connection conn_xxx
@@ -202,17 +257,22 @@ tangle hub github-app mint-installation-token --repo-url https://github.com/owne
 
 ## Secrets
 
-Secrets are scoped to your account (or team). Use `--reveal` to see values.
+Secrets are scoped to your account (or team). Values never round-trip: `create`, `list`, `delete` only. At create time a bare `--secret NAME` is box delivery; proxy custody is `--proxy-secret`.
 
 ```bash
 tangle secret create DATABASE_URL "postgres://..."
 tangle secret create API_KEY    # prompts interactively
 tangle secret list
-tangle secret show DATABASE_URL --reveal
-tangle secret update DATABASE_URL "new-value"
 tangle secret delete DATABASE_URL
 ```
 
+Canonical proxy custody at create time — the value never enters the box:
+
+```bash
+tangle sandbox create --proxy-secret '{"envName":"PROVIDER_KEY","secretRef":{"kind":"secret-ref","key":"PROVIDER_KEY"},"presentation":{"type":"bearer"},"hosts":["api.example.org"]}'
+tangle sandbox create --proxy-secret @bindings.json   # repeatable; array or single binding
+```
+
 ## Snapshots
 
 ```bash
@@ -257,7 +317,13 @@ 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
@@ -266,7 +332,9 @@ https://sandbox.tangle.tools/docs/workflows
 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>
@@ -291,6 +359,7 @@ 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>
@@ -328,10 +397,6 @@ tangle backend restart <sandboxId>
 tangle env ls
 tangle env get <id>
 
-# Tools (mise)
-tangle tools ls <id>
-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
@@ -354,10 +419,6 @@ tangle mcp serve <id>
 tangle preview ls <id>
 tangle preview create <id> 3000
 tangle preview rm <id> <preview-id>
-
-# Sandbox user permissions
-tangle permissions list <sandboxId>
-tangle permissions add <sandboxId> --userId <userId> --role editor
 ```
 
 ## Common Workflows
@@ -375,7 +436,6 @@ tangle permissions add <sandboxId> --userId <userId> --role editor
 
 ## 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` when piping output:** many commands need explicit `--json` for machine-readable output.

package/dist/graph-native-af-gs1TS.mjs

@@ -0,0 +1 @@
+import{constants as e}from"node:fs";import{isAbsolute as t,join as n,relative as r}from"node:path";import{z as i}from"zod";import{open as a,opendir as o,realpath as s}from"node:fs/promises";import*as c from"@tangle-network/agent-runtime/kernel";import{CODEX_HOME_RULE as l,codexRefForFile as u,readSessionInput as d,storeGlob as f,withinPath as p}from"@tangle-network/harness-sessions";const m=i.object({harness:i.literal(`codex`),root:i.string().refine(t),basis:i.literal(`host-jail`),nativeSessionId:i.string().min(1),runId:i.string().min(1),requestDigest:i.string().regex(/^sha256:[a-f0-9]{64}$/)}),h=i.object({externalId:i.string(),internalId:i.string(),backend:i.literal(`codex`),cwd:i.string(),metadata:i.object({effective_native_store:m,agent_profile_binding:i.object({effectiveProfileDigest:i.string()})})});async function g(e,t){let i=[],a=l.sessionDirs.map(t=>n(e,t)),d=f(l.rollout),m=0;for(;a.length;){t.throwIfAborted();let l=a.shift();if(l===void 0)break;let f;try{f=await s(l)}catch(e){if(e.code===`ENOENT`)continue;throw e}if(!p(f,e))throw Error(`Native inventory escaped its attested store`);let h=await o(f);for await(let o of h){if(t.throwIfAborted(),++m>c.HARNESS_TRANSCRIPT_READ_LIMITS.maxFiles)throw Error(`Native inventory exceeds the capture bound`);let s=n(h.path,o.name);o.isDirectory()?a.push(s):o.isFile()&&d.test(o.name)&&i.push({path:r(e,s),nativeSessionId:u(s).nativeSessionId})}}return i}function _(t){return async r=>{if(r.harness!==`codex`)return{status:`unavailable`,reason:`unknown-harness`,skipped:[{path:r.harness,reason:`Native transcript capture is not configured for this harness`}]};let o=await fetch(`${t.bridgeUrl}/v1/sessions?session_id=${encodeURIComponent(r.sessionId)}&backend=${r.harness}`,{headers:{authorization:`Bearer ${t.bridgeBearer}`},signal:r.signal});if(!o.ok)throw Error(`Bridge session lookup failed (HTTP ${o.status})`);let l=i.object({data:i.tuple([h])}).parse(await o.json()).data[0],u=l.metadata.effective_native_store,f=await s(u.root);if(l.externalId!==r.sessionId||l.internalId!==u.nativeSessionId||l.cwd!==t.cwd||r.cwd!==t.cwd||l.metadata.agent_profile_binding.effectiveProfileDigest!==r.profileDigest||f!==u.root||!p(f,n(t.cwd,`.agent-home`))||!r.runs.some(e=>e.runId===u.runId&&e.requestDigest===u.requestDigest))throw Error(`Bridge native binding does not match this execution`);return c.captureBoundHarnessTranscript({harness:r.harness,binding:{kind:`bridge`,sessionId:r.sessionId,nativeSessionId:u.nativeSessionId,profileDigest:r.profileDigest,runs:r.runs,...r.node===void 0?{}:{node:r.node}},nativeSessionId:u.nativeSessionId,files:await g(f,r.signal),signal:r.signal,parse:(e,t)=>d(r.harness,{text:e},{nativeSessionId:t.nativeSessionId,label:t.path},{corruption:`strict`}),read:async(t,r)=>{let i=await s(n(f,t.path));if(!p(i,f))throw Error(`Native session escaped its attested store`);let o=await a(i,e.O_RDONLY|e.O_NOFOLLOW);try{let e=await o.stat();if(!e.isFile()||e.size>c.HARNESS_TRANSCRIPT_READ_LIMITS.maxFileBytes)throw Error(`Native session is not a bounded regular file`);r?.throwIfAborted();let t=await o.readFile();return r?.throwIfAborted(),t}finally{await o.close()}}})}}const v=async(e,t)=>{if(e.harness!==`codex`||e.binding?.kind!==`bridge`)throw Error(`Native transcript reader is not configured for this capture`);return(await c.readBoundHarnessSessions({nativeSessionId:e.binding.nativeSessionId,files:e.files.map(e=>({path:e.path,nativeSessionId:u(e.path).nativeSessionId,byteLength:e.bytes})),read:async t=>{let n=e.files.find(e=>e.path===t.path);if(!n)throw Error(`Retained native file is absent`);return Buffer.from(n.content,`utf8`)},parse:(e,t)=>d(`codex`,{text:e},{nativeSessionId:t.nativeSessionId,label:t.path},{corruption:`strict`}),signal:t})).sessions};export{_ as graphNativeCapture,v as readGraphSessions};