@tangle-network/sandbox-cli 0.22.102 → 0.22.104

package/README.md

@@ -87,10 +87,190 @@ Progress goes to stderr; `--json` returns the result or the shared error contrac
 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`.
 
+To learn from retained runs, admit related tasks under the same independent unit
+and keep each unit in one partition. Repeating ingestion updates that run's
+checkpoint without adding another example. Unavailable runs remain visible with
+evidence gaps; lifecycle completion never becomes a quality label.
+
+```bash
+tangle --json graph dataset ./runs <run-id> --domain software --unit repository-a --split train
+tangle --json graph dataset ./runs <another-run-id> --domain software --unit repository-b --split dev
+tangle --json graph dataset ./runs <heldout-run-id> --domain software --unit repository-c --split test
+tangle --json graph improve ./delivery.graph.yaml ./runs --suite ./software-evaluation.json --campaign ./campaign
+tangle --json graph activate ./campaign ./delivery.graph.yaml
+tangle --json graph observe ./campaign <subsequent-run-id> --unit new-production-task
+```
+
+For local tasks that depend on repository files, first capture one explicit Git root while its other writers are idle. The capture uses Runtime's maintained archive and limits. It retains HEAD, the index, tracked files and unignored untracked files in private local artifacts. Keep the reference outside the repository:
+
+```sh
+tangle --json graph workspace capture ./repository --output ./task-workspace.json
+tangle --json graph run ./factory.graph.yaml --task-workspace ./task-workspace.json --param task=example
+```
+
+Dataset ingestion retains that exact workspace reference, and learning materializes it into every fresh candidate's private directory. Retries reuse the same allocation and preserve agent edits; a standalone dry-run releases only its own fresh validation copy. Missing or corrupt archive bytes refuse fresh replay; capture never executes repository scripts. Environment variables, installed tools and Git-ignored files are not snapshotted. Tracked files and Git history may contain private data; these artifacts remain local, and cloud dispatch refuses these local-only references. Legacy runs without captures retain a `task-workspace-not-snapshotted` gap rather than acquiring an unrelated current workspace.
+
+Datasets retain exact trigger payloads and captured MCP host policies. Legacy manifests that omitted trigger context must be reingested before learning. `dispatch`, `improve` and `repair` accept `--mcp-policy` and private `--mcp-secret key=ENVIRONMENT_VARIABLE` bindings; secret values and environment variable names are not campaign identities.
+
+Each graph, including the proposer, reserves its complete declared ceiling through Runtime's budget pool and reconciles only its matching retained settlement. Restart verifies every previously hashed settlement and replays its actual spend through the same owner pool, preserving cache and dollar completeness; missing or inconsistent historical receipts hold. An interrupted reservation keeps the exact run ID, input and compiled graph during the owner's resume attempt. An unavailable native attachment or unknown usage cannot authorize replacement work or a new comparison. Eval may close an interrupted proposal as failed even when its native evidence is recovered. Recovered final-test cells with incomplete end-to-end latency hold the operational comparison instead of appearing artificially fast. Supplied benchmark arms use content-addressed source snapshots throughout a campaign.
+
+Activation locks the canonical target across campaigns and rechecks its bytes after evaluator calibration and immediately before replacement. Atomic rename does not provide a filesystem compare-and-swap against unrelated editors. Activation also recompiles each measured case with ordinary execution settings and refuses a seat override or changed default that would not carry into an ordinary run. It freezes measured harness/model/seat/connection selections and MCP policy from retained compiled graph records. Observations verify those frozen host selections without consulting today's defaults, while allowing new task inputs through the same authored source. Missing execution records, historical activation records without this binding, and previously unmeasured selections refuse observation. Observations must start after activation, exclude every campaign execution, and identify a new production task unit with inputs distinct from the learning cohort and earlier observations. Repeating the same observation returns its retained verdict; another run cannot count that unit or task again.
+
+The evaluation suite is JSON with `version: 1`, `domain`, the inline-prompt
+`node` to improve, `objective`, `minimumEffect` and `reps`. Its `evaluator`
+declares an absolute executable `command`, `args`, `files` (every script, rubric and data dependency)
+and `timeoutMs`. The command reads one JSON request from stdin and emits exactly
+`{"quality": 0.0, "notes": "independent outcome evidence"}` on stdout. Requests
+contain `scenario`, retained `evidence`, and the candidate `artifact`, including
+its native run ID, output, measured usage and duration. The evaluator runs outside
+the candidate's workspace. Include `calibration` entries with a `request` and
+independently known `quality` of zero or one; both classes must pass before
+inference begins. A failed evaluator is an unmeasured cell, never a quality zero.
+Evaluator commands follow the operator's subscription-only spending policy.
+
+The suite's `budget` requires total `maxTokens`, `maxIterations`, `deadlineMs`,
+`maxExpansions`, plus `proposalTokens`, `proposalIterations` and
+`proposalDeadlineMs`. The graph also declares finite per-run budgets. Runtime's
+existing reflective proposer generates detached prompt candidates, and its search
+owns train/selection/final-test partitions, paired decisions and the closed
+ledger. A single conserved Runtime pool bounds native candidate and proposal
+calls; interruption retains the pending ceiling conservatively. Reusing a
+finished campaign returns its exact retained result. Subscription-only execution forbids provider billing; an observed billed charge holds further work. Operating costs remain explicitly unknown.
+The suite also requires `operatingConstraints.maxMeanTokens` and
+`operatingConstraints.maxMeanDurationMs`. Only candidates with a fully matched
+final-test cohort, known reported tokens, and measured end-to-end cell latency
+including queueing can enter Eval's quality/token/latency frontier. Activation
+requires those ceilings as well as the independent quality decision. Setting
+`operatingConstraints.requireKnownOperatingCost` to true holds while environment
+and subscription allocation costs are unknown; the report does not claim a
+dollar frontier. Evaluator bytes are checked before and after every score and
+again before the decision is retained.
+
+Activation requires Runtime's independent final-test promotion, unchanged
+evaluator dependencies, the exact measured candidate bytes and the original
+baseline. A hold leaves the graph unchanged. Subsequent runs are graded into
+separate observation records. The selected change is one authored inline
+`prompt.systemPrompt`, otherwise `prompt.appendSystemPrompt`, compiled separately
+for each task. An unchanged candidate preserves the original source bytes.
+Full-profile, structure, code and Knowledge candidate generation stay with their
+existing owners and are not activated by this command.
+
+The optional suite `optimizer` defaults to `{ "kind": "native" }`. Set `kind` to
+`gepa` and choose `recipe.kind: "engine"`, with `recipe.run.maxEvaluations`, or
+`recipe.kind: "omni"`, with `recipe.explore` runs and `recipe.continueWith`.
+Both use Runtime's official GEPA implementation, the same retained proposal runs,
+independent grader and campaign pool. Supply the request, response, candidate,
+evidence and model-request bounds declared in the [maintained optimizer schema](src/lib/graph-optimizer.ts).
+Campaign work is serialized by the retained-attempt contract; larger engine/Omni worker counts refuse.
+GEPA resume requires an explicit compatible-state policy and `trustLocalState`;
+Omni requires `resume: "never"`. These adapters accept ordered text reflection
+requests through an explicit native JSON-content protocol. They refuse tools,
+images and unsupported model controls before dispatch. The legacy js-issues replay remains available
+without `--suite`; it matches seats across arms and accepts total replay
+`--max-tokens`, `--max-iterations` and `--deadline-ms` ceilings.
+
+Native graph nodes can use Knowledge through Runtime's existing authenticated
+coordination MCP. Declare only the tools the node needs in `profile.tools`:
+`agent_runtime_coordination_knowledge_search`, `..._knowledge_read`,
+`..._knowledge_record`, and `..._knowledge_resolve`. Declare a native graph input
+`knowledge: { default: null }` to make the binding optional. Only `null` or an omitted binding disables Knowledge; every other value must pass the existing strict local/Hub binding schema. The local binding
+comes from `tangle --json graph knowledge bind ./knowledge-store`; supply that
+JSON as `--param knowledge=<JSON>`. It pins the curated store's exact hash, reads
+that view, and writes proposed changes only to private run stores. A changed
+curated hash refuses retrieval rather than silently selecting new knowledge.
+
+Hosted bindings use `{"kind":"hub","references":[{"sourceId":"...","generation":"kg_..."}]}`.
+The workflow owner materializes those exact references for the admitted native
+node's sandbox and uses Knowledge's existing live credential, attachment and
+connection checks. Each returned lexical retrieval retains a Knowledge receipt,
+canonical visibility, source identities, generation, query and trusted Runtime
+run/node/profile identity before delivering the result. Hosted vector retrieval
+with graph receipts refuses before embedding calls until that spending has an
+enforced budget. Hosted `knowledge_record` retains an isolated, unevaluated
+proposal artifact and leaves published generations unchanged.
+
+An independently measured local candidate reference from the maintained Knowledge
+improvement API can be applied with `graph knowledge promote <binding.json>
+<candidate.json>` or restored with `graph knowledge restore`. Knowledge verifies
+the exact baseline, candidate and evaluation identities and performs its durable
+transaction. The command returns the next exact binding. Hub generation
+activation through this file-backed candidate API is explicitly unsupported;
+Hub source publication remains with its existing owner. Retrieval and a proposed
+write do not establish an improvement.
+
 `--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.
+immediately. Later runs reuse that named deployment without changing its triggers.
+Changed source or bindings require `graph apply` first. 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.
+
+Publish without starting a run, then run the exact deployed revision:
+
+```bash
+tangle graph apply haiku-review --deploy ./deploy.yaml --dry-run --json
+tangle graph apply haiku-review --deploy ./deploy.yaml --json
+tangle graph run haiku-review --workflow <workflow-id> --json
+tangle workflows get <workflow-id>
+```
+
+Deployment settings use the existing Hub Workflow graph deployment contract,
+separate from the portable graph. `--param` and `--seat` override the file's
+defaults. The platform validates trigger availability, connections and schedules.
+For example:
+
+```yaml
+name: weekly-audit
+enabled: true
+on:
+  - schedule:
+      cron: "0 8 * * 1"
+      timezone: America/Los_Angeles
+  - webhook: {}
+```
+
+A provider event can instead declare
+`provider_event: { connection: github, event: issues, actions: [opened], repo: example/project }`.
+The graph must consume that event's `trigger` data; declaring a subscription does
+not map an event to a static graph parameter. Provider action tools do not imply
+that a deployment can receive its events.
+
+An API key's expiry also bounds any schedule it authors. Set `schedule.until`
+within that grant, or use an owner credential whose authority covers the intended
+schedule. Dry-run reports `schedule_outlives_grant` before publication when it does
+not; a browser login's short-lived CLI key does not grant indefinite recurrence.
+
+`apply` matches one workflow by name, or `--workflow <id>` selects it explicitly.
+An unchanged resolved graph and deployment create no revision for manual, webhook
+or scheduled jobs. Provider-event apply refreshes the owner's ingress bindings,
+including after a reconnect. First publication reserves
+one paused, manual graph atomically, then applies the requested revision and its
+triggers. A failed first update leaves that reservation paused and retryable. Concurrent
+different updates conflict instead of overwriting one another. Use distinct names
+for different deployed jobs. Deployment settings contain references and policy,
+never credential values.
+
+After configuring a webhook, explicitly mint its bearer with
+`tangle graph webhook <workflow-id> --rotate`. The JSON response reveals the new
+bearer once and retires the previous one; keep it in the receiver's secret store.
+It is not written into graph source or deployment settings.
+
+For local recurring work, an OS scheduler or webhook receiver owns the trigger
+and calls the same durable local executor:
+
+```bash
+tangle graph dispatch weekly-audit --event ./event.json --delivery schedule:2026-11-16T08:00:00-08:00 --json
+```
+
+The event file is a JSON object visible as `trigger` in the graph. Use the same
+delivery id for retries and the nominal scheduled occurrence, not the retry time.
+The private `~/.tangle/deliveries` record binds that delivery to one Runtime run,
+source, workspace, event and parameters. Retries resume that run. A completed
+result replays without starting another native execution. Changed event or graph
+bytes refuse the reused id; concurrent delivery attempts refuse while the owner
+holds the delivery lock. A failed terminal run requires inspection and an explicit
+new delivery. Local dispatch does not install a daemon or expose a public webhook;
+the scheduler/receiver must remain running and manage provider authentication.
 
 `--resume` restores saved inputs and rejects changed source, parameters, seat
 settings or placement. A completed winner returns its retained result without
@@ -360,3 +540,18 @@ 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.
+
+A graph deployment can bind an owner Sandbox template or snapshot without changing the graph source:
+
+```yaml
+name: crm-audit
+mcpPolicy:
+  allowedMcpHosts: [crm.example.com]
+sandbox:
+  templateId: my-owner-template
+  secrets: [CRM_TOKEN]
+```
+
+`secrets` names entries already stored in the owner's Sandbox vault. A profile's MCP `secret-ref.key` uses that same name; the private sidecar materializer resolves its value. Apply and cloud run never read or upload local environment values. Missing or unselected refs fail before native dispatch. Select `publicTemplateId` with optional `publicTemplateVersionId`, or both `fromSandboxId` and `fromSnapshot`, instead of `templateId`. Sandbox checks source ownership and capabilities through its normal creation API. A recovered Runtime checkpoint takes precedence over the deployment's initial source.
+
+An isolated check opts into the same Sandbox binding with `environment: deployment`; its shell uses the restored `/home/agent`. Built-in `universal` and `agent-container` checks keep their existing placement. Check secrets still use the graph repository credential contract. Custom scripts needing other credentials run through the admitted native Sandbox or MCP tool path; isolated checks receive no owner vault grants.

package/SKILL.md

@@ -73,8 +73,37 @@ 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>
+# Custom MCP host admission and private local env binding:
+tangle graph run reviewed-change --mcp-policy host-policy.json --mcp-secret tool-account=TOOL_ACCOUNT_TOKEN
 ```
 
+Custom MCP admission comes from the host policy file. Local `--mcp-secret key=ENV_NAME`
+binds a declared AgentProfile secret reference without recording the environment name
+or value in graph identities. Cloud runs refuse this local flag and use their own
+owner-vault bindings. Echoed values are redacted before local process retention and
+native transcript copies. A transformed native capture reports incomplete original
+bytes and the source hash; the vendor source file stays unchanged.
+
+For recurring or provider-driven work, apply the captured deployment first and
+inspect its returned workflow ID/revision. Run that workflow explicitly; inspect
+the returned run ID and retained artifacts before reporting success. The
+[Graph factories guide](README.md#graph-factories) owns deployment bindings,
+cron/webhook/provider triggers, local event dispatch, and evaluation suite setup.
+
+```bash
+tangle --json graph apply reviewed-change --deploy ./deploy.yaml
+tangle --json graph run reviewed-change --workflow <workflow-id>
+tangle --json graph inspect <run-id> --artifacts
+tangle --json graph inspect <run-id> --artifact <node/path> --out ./retained.log
+```
+
+Use `graph dataset` to retain admitted attempts, including interrupted or
+unavailable ones. Select independent task units and train/dev/test partitions
+before `graph improve --suite`; inspect the exact promotion or hold result before
+`graph activate`, then use `graph observe` on subsequent work. Process completion
+alone is not a quality label. For Knowledge tools and exact bindings, read the
+same guide before configuring node tool permissions.
+
 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,

package/dist/graph-native-Cl6SphYB.mjs

@@ -0,0 +1 @@
+import{createHash as e}from"node:crypto";import{constants as t}from"node:fs";import{isAbsolute as n,join as r,relative as i}from"node:path";import{z as a}from"zod";import{open as o,opendir as s,realpath as c}from"node:fs/promises";import*as l from"@tangle-network/agent-runtime/kernel";import{CODEX_HOME_RULE as u,STORES as d,claudeCodeRefForFile as f,codexRefForFile as p,readSessionInput as m,storeGlob as h,withinPath as g}from"@tangle-network/harness-sessions";const _=a.object({harness:a.enum([`codex`,`claude-code`]),root:a.string().refine(n),basis:a.literal(`host-jail`),nativeSessionId:a.string().min(1),runId:a.string().min(1),requestDigest:a.string().regex(/^sha256:[a-f0-9]{64}$/)}),v=a.object({externalId:a.string(),internalId:a.string(),backend:a.enum([`codex`,`claude-code`]),cwd:a.string(),metadata:a.object({effective_native_store:_,agent_profile_binding:a.object({effectiveProfileDigest:a.string()})})});function y(){let e=new Map;return{observe(t){e.set(`${t.runId}:${t.requestDigest}`,t)},close(){e.clear()},redact(t,n){for(let n of t.runs){let r=e.get(`${n.runId}:${n.requestDigest}`);if(!r||r.sessionId!==t.sessionId||r.profileDigest!==t.profileDigest||r.cwd!==t.cwd)throw Error(`Exact native execution has no trusted redaction authority`)}if(!t.runs.length)throw Error(`Native redaction requires an exact execution binding`);let r=n;for(let n of e.values())n.sessionId===t.sessionId&&n.profileDigest===t.profileDigest&&n.cwd===t.cwd&&(r=n.redact(r));return r}}}function b(e,t){if(e===`codex`)return p(t);let n=t.split(`/`),r=n.indexOf(`subagents`,3);return f(t,r>0?n[r-1]??null:null)}async function x(e,t,n){let a=[],o=d[`claude-code.projects-jsonl`],f=r(t,...o.root.split(`/`).slice(1)),p=e===`codex`?u.sessionDirs.map(e=>r(t,e)):[f],m=e===`codex`?[h(u.rollout)]:o.files.map(e=>h(e)),_=0;for(;p.length;){n.throwIfAborted();let o=p.shift();if(o===void 0)break;let u;try{u=await c(o)}catch(e){if(e.code===`ENOENT`)continue;throw e}if(!g(u,t))throw Error(`Native inventory escaped its attested store`);let d=await s(u);for await(let o of d){if(n.throwIfAborted(),++_>l.HARNESS_TRANSCRIPT_READ_LIMITS.maxFiles)throw Error(`Native inventory exceeds the capture bound`);let s=r(d.path,o.name);o.isDirectory()?p.push(s):o.isFile()&&m.some(t=>t.test(e===`codex`?o.name:i(f,s)))&&a.push({path:i(t,s),nativeSessionId:b(e,i(t,s)).nativeSessionId})}}return a}function S(n){return async i=>{if(![`codex`,`claude-code`].includes(i.harness))return{status:`unavailable`,reason:`unknown-harness`,skipped:[{path:i.harness,reason:`Native transcript capture is not configured for this harness`}]};let s=await fetch(`${n.bridgeUrl}/v1/sessions?session_id=${encodeURIComponent(i.sessionId)}&backend=${i.harness}`,{headers:{authorization:`Bearer ${n.bridgeBearer}`},signal:i.signal});if(!s.ok)throw Error(`Bridge session lookup failed (HTTP ${s.status})`);let u=a.object({data:a.tuple([v])}).parse(await s.json()).data[0],d=u.metadata.effective_native_store,f=await c(d.root);if(u.backend!==i.harness||d.harness!==i.harness||u.externalId!==i.sessionId||u.internalId!==d.nativeSessionId||u.cwd!==n.cwd||i.cwd!==n.cwd||u.metadata.agent_profile_binding.effectiveProfileDigest!==i.profileDigest||f!==d.root||!g(f,r(n.cwd,`.agent-home`))||!i.runs.some(e=>e.runId===d.runId&&e.requestDigest===d.requestDigest))throw Error(`Bridge native binding does not match this execution`);let p=[],h=[...new Set(n.privateMcpSecrets?.()??[])].flatMap(e=>[e,JSON.stringify(e).slice(1,-1)]).filter(Boolean).sort((e,t)=>t.length-e.length),_=await l.captureBoundHarnessTranscript({harness:i.harness,binding:{kind:`bridge`,sessionId:i.sessionId,nativeSessionId:d.nativeSessionId,profileDigest:i.profileDigest,runs:i.runs,...i.node===void 0?{}:{node:i.node}},nativeSessionId:d.nativeSessionId,files:await x(i.harness,f,i.signal),signal:i.signal,parse:(e,t)=>m(i.harness,{text:e},{...b(i.harness,t.path),label:t.path},{corruption:`strict`}),read:async(a,s)=>{let u=await c(r(f,a.path));if(!g(u,f))throw Error(`Native session escaped its attested store`);let d=await o(u,t.O_RDONLY|t.O_NOFOLLOW);try{let t=await d.stat();if(!t.isFile()||t.size>l.HARNESS_TRANSCRIPT_READ_LIMITS.maxFileBytes)throw Error(`Native session is not a bounded regular file`);s?.throwIfAborted();let r=await d.readFile();if(s?.throwIfAborted(),!n.redact)throw Error(`The native host did not supply private redaction authority`);let o=n.redact(i,r),c=new TextDecoder(`utf-8`,{fatal:!0}).decode(o);for(let e of h)c=c.split(e).join(`[redacted:MCP]`);let u=Buffer.from(c,`utf8`);return u.equals(r)||p.push({path:a.path,reason:`Original bytes withheld for private MCP credential redaction; source sha256:${e(`sha256`).update(r).digest(`hex`)}; retained copy is redacted`}),u}finally{await d.close()}}});return _.status!==`captured`||!p.length?_:{..._,artifact:{..._.artifact,skipped:[..._.artifact.skipped,...p]},skippedCount:_.skippedCount+p.length,coverageComplete:!1,missing:[`private-mcp-secret-original-bytes`]}}}const C=async(e,t)=>{if(![`codex`,`claude-code`].includes(e.harness)||e.binding?.kind!==`bridge`)throw Error(`Native transcript reader is not configured for this capture`);return(await l.readBoundHarnessSessions({nativeSessionId:e.binding.nativeSessionId,files:e.files.map(t=>({path:t.path,nativeSessionId:b(e.harness,t.path).nativeSessionId,byteLength:t.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:(t,n)=>m(e.harness,{text:t},{...b(e.harness,n.path),label:n.path},{corruption:`strict`}),signal:t})).sessions};export{S as graphNativeCapture,y as graphNativeRedaction,C as readGraphSessions};