@tangle-network/sandbox-cli 0.21.64 → 0.21.66

package/README.md

@@ -15,7 +15,7 @@ See [Limitations](#limitations) for open gaps.
 
 ## Install
 
-One-liner (requires Node on PATH matching the package's [`engines` metadata](./package.json)):
+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,7 +52,7 @@ pnpm --filter @tangle-network/sandbox-cli build
 node products/sandbox/cli/bin/tangle.js --help
 ```
 
-## Local graphs
+## 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
@@ -63,6 +63,9 @@ critic and a declared completion check.
 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
@@ -75,9 +78,34 @@ exact `tangle hub connect <provider>` command. Ctrl-C cancels login, connection
 polling and pending Hub requests.
 
 Progress goes to stderr; `--json` returns the result or the shared error contract
-on stdout. Run journals live under `~/.tangle/runs/<run-id>`, and graph history
+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.
@@ -105,7 +133,7 @@ Credential lookup precedence:
 1. `--api-key` flag
 2. `TANGLE_API_KEY_FILE` managed credential file
 3. `TANGLE_API_KEY` environment variable
-4. `~/.tangle/credentials` (populated by `tangle auth login`)
+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.

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
@@ -61,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
@@ -229,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
@@ -403,7 +436,6 @@ tangle preview rm <id> <preview-id>
 
 ## 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-CS_TmaCK.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{open as i,opendir as a,realpath as o}from"node:fs/promises";import{z as s}from"zod";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=s.object({harness:s.literal(`codex`),root:s.string().refine(t),basis:s.literal(`host-jail`),nativeSessionId:s.string().min(1),runId:s.string().min(1),requestDigest:s.string().regex(/^sha256:[a-f0-9]{64}$/)}),h=s.object({externalId:s.string(),internalId:s.string(),backend:s.literal(`codex`),cwd:s.string(),metadata:s.object({effective_native_store:m,agent_profile_binding:s.object({effectiveProfileDigest:s.string()})})});async function g(e,t){let i=[],s=l.sessionDirs.map(t=>n(e,t)),d=f(l.rollout),m=0;for(;s.length;){t.throwIfAborted();let l=s.shift();if(l===void 0)break;let f;try{f=await o(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 a(f);for await(let a of h){if(t.throwIfAborted(),++m>c.HARNESS_TRANSCRIPT_READ_LIMITS.maxFiles)throw Error(`Native inventory exceeds the capture bound`);let o=n(h.path,a.name);a.isDirectory()?s.push(o):a.isFile()&&d.test(a.name)&&i.push({path:r(e,o),nativeSessionId:u(o).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 a=await fetch(`${t.bridgeUrl}/v1/sessions?session_id=${encodeURIComponent(r.sessionId)}&backend=${r.harness}`,{headers:{authorization:`Bearer ${t.bridgeBearer}`},signal:r.signal});if(!a.ok)throw Error(`Bridge session lookup failed (HTTP ${a.status})`);let l=s.object({data:s.tuple([h])}).parse(await a.json()).data[0],u=l.metadata.effective_native_store,f=await o(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 a=await o(n(f,t.path));if(!p(a,f))throw Error(`Native session escaped its attested store`);let s=await i(a,e.O_RDONLY|e.O_NOFOLLOW);try{let e=await s.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 s.readFile();return r?.throwIfAborted(),t}finally{await s.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};