@tangle-network/sandbox-cli 0.21.64 → 0.21.65

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.

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

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};