feat(provider): define exact process environments

[drewstone]

Problem

Approved candidate execution needs one provider-neutral contract instead of each product hand-writing Sandbox create, process, file, recovery, and cleanup logic.

Change

• Add the exact-process environment contract to agent-interface.
• Add reusable lifecycle checks in agent-provider-testkit.
• Add the Tangle Sandbox adapter with immutable-image, explicit-resource, bounded-byte-read, terminal-reason, and idempotent-recovery behavior.
• Require Sandbox 0.12.0 because earlier SDKs lack the exact-process API.

Local checks

• agent-interface: TypeScript and 139 tests
• agent-provider-testkit: TypeScript and 4 tests
• agent-provider-tangle: TypeScript and 4 tests

Release order: publish Sandbox 0.12.0 before the Tangle adapter.

[tangletools]

✅ Auto-approved drewstone PR — eda63ce9

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-07-18T14:08:47Z}

[tangletools]

🟡 Value Audit — sound-with-nits

Verdict	sound-with-nits
Concerns	1 (1 weak-concern)
Heuristic	0.0s
Duplication	0.0s
Interrogation	138.7s (2 bridge agents)
Total	138.7s

💰 Value — sound-with-nits

Adds a single optional provider-neutral exact-process execution contract (with a Tangle adapter and conformance harness) so approved candidates can run on any compliant provider without per-product sandbox plumbing — coherent and in-grain.

• What it does: Defines a new optional AgentExactProcessProvider capability on the existing AgentEnvironmentProvider (environment-provider.ts:196-206, :361) covering shell-free spawn, byte-bounded file IO, recoverable process handles, idempotent create with collision rejection, and terminal-reason status. Adds a Tangle Sandbox adapter (agent-provider-tangle/src/exact-process.ts) that maps the contract onto @t
• Goals it achieves: Give higher-level runtimes one provider-neutral primitive for executing an approved AgentCandidateExecution/AgentCandidateExecutionPlanMaterial on any compliant provider, instead of each product hand-writing Sandbox create + spawn + file + recovery + cleanup. README at agent-interface/README.md:65-70 states this explicitly: 'Higher-level runtimes can use this primitive for measured candidates
• Assessment: Sound and in the grain of the codebase. The capability is added as an optional member of the existing provider interface rather than a parallel hierarchy, reuses AgentCandidateTermination from agent-candidate.ts as the terminal-reason type, and matches the existing testkit conformance pattern (runAgentEnvironmentProviderConformance). The Tangle adapter is one focused file with clean helpers, a
• Better / existing approach: none — this is the right approach. I checked: (a) the existing AgentEnvironment.exec?(command, options) at environment-provider.ts:299 is a loose shell-string one-shot tied to the agent-turn model — no recovery, no byte bounds, no idempotency, no attestation; the README at agent-interface/README.md:68 enumerates the seven guarantees that distinguish the new contract from it. (b) `AgentCandidateE
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 2
• Bridge warning: opencode/kimi-for-coding/k2p7: bridge stream ended without value-audit content

🎯 Usefulness — sound

A provider-neutral, shell-free exact-process primitive that completes the candidate-execution runtime surface already encoded in this repo's schemas — clean, well-tested, no dead or competing surface.

• Integration: The new AgentExactProcessProvider (environment-provider.ts:196-206) hangs off the established AgentEnvironmentProvider via an optional exactProcess field (environment-provider.ts:361), mirrors the existing create/get/list shape, and is wired through createTangleProvider({ exactProcess: {} }) (index.ts:142-152). No in-tree product caller invokes it yet — by design: this is the SDK contrac
• Fit with existing patterns: Fits the established pattern exactly. The repo already ships agent-provider-{tangle,e2b,daytona,computesdk,cli-bridge} adapters around AgentEnvironmentProvider; the new exactProcess capability is an opt-in extension on the same interface with the same create/get/list shape. It does NOT compete with AgentEnvironment.exec() — that one is a shell-exec for interactive agent sessions, while e
• Real-world viability: The adapter covers realistic paths beyond the happy path: idempotent recovery via attestation equality (exact-process.ts:57-72), collision rejection when key is reused with different inputs (exact-process.ts:68-72), team-scoped list with pagination (exact-process.ts:89-104), immutable-image enforcement via sha256-digest regex (exact-process.ts:24, 115-117), bounded byte reads double-checked before
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

💰 Value Audit

🟡 PATH-required validation logic is written three times [duplication] ``

The 'relative executable/interpreter requires non-empty env.PATH' rule is implemented independently in agent-candidate-code-schema.ts:246-255, agent-candidate-execution-plan-schema.ts:423-430, and validateExactProcessLaunch at agent-provider-tangle/src/exact-process.ts:276. The two schema-level copies have nearly identical shape and message and could be extracted into a shared helper in agent-candidate-schema-common.ts (which already exists for shared schema utilities). The runtime check is at a

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260718T141247Z}

[tangletools]

❌ Needs Work — eda63ce9

Review health 100/100 · Reviewer score 0/100 · Confidence 95/100 · 23 findings (2 critical, 4 medium, 17 low)

glm: Correctness 0 · Security 0 · Testing 0 · Architecture 0

Reviewer score is advisory once the run is complete and the verdict has no blockers.

Full multi-shot audit completed 8/8 planned shots over 19 changed files. Global verifier still owns final merge decision.

Blocking

🟣 CRITICAL peerDependency sandbox >=0.12.0 unsatisfiable; devDep pinned to ^0.11.1 — packages/agent-provider-tangle/package.json

peerDependencies declares "@tangle-network/sandbox": ">=0.12.0 <1.0.0" but devDependencies pins "^0.11.1". Per semver, ^0.11.1 resolves to >=0.11.1 <0.12.0, which does NOT satisfy the peer. pnpm-lock.yaml confirms the repo installs @tangle-network/sandbox@0.11.1. npm view @tangle-network/sandbox dist-tags shows latest=0.11.1 with no 0.12.x ever published, so no consumer can satisfy this peer at all. Impact: publishing this version produces peer-dependency install errors for every external user (and the repo's own pnpm install --strict-peer-dependencies will fail). Fix: either bump devDependency to "^0.12.0" once 0.12.0 is published and align both, or lower the peer to ">=0.11.1 <1.0.0" to match what actually exists. The previous pair (peer >=0.8.0, dev ^0.8.2) was internally consistent

🟣 CRITICAL Code imports names that do not exist in the locked @tangle-network/sandbox version; build/typecheck/tests fail — packages/agent-provider-tangle/src/exact-process.ts

Verified concretely: pnpm check-types produces 7 errors — TS2305 on createExactProcessAttestation, parseExactProcessAttestation, ExactProcessAttestation (exact-process.ts:4,6,7 and index.ts:4, plus index.test.ts:7,9); TS2322 on EgressPolicy.includeImplicitDomains (exact-process.ts:158); TS2339 on CreateSandboxOptions.exactProcess (index.test.ts:238). pnpm test fails 2/4 with TypeError: createExactProcessAttestation is not a function. The pnpm-lock.yaml only resolves @tangle-network/sandbox@0.11.1; the bumped peerDep >=0.12.0 is unsatisfiable in-repo and the devDep ^0.11.1 was not bumped alongside. Fix: bump devDep + lockfile to the sandbox release that ships these exports (and the exactProcess/includeImplicitDomains fields), or vendor/define the attestation helper

Other

🟠 MEDIUM Personal-mode filter rejects sandboxes whose teamId is auto-assigned by the platform — packages/agent-provider-tangle/src/exact-process.ts

The branch teamId ? box.teamId !== teamId : box.teamId !== undefined means: when no provider teamId is configured, any sandbox whose instance carries a non-undefined teamId is treated as not-an-exact-process and dropped from get() / list(). If the Tangle platform ever populates teamId automatically for personal accounts (some platforms assign a personal-team id), all personal-mode exact-process sandboxes become invisible after creation. The mock test always assigns teamId explicitly so this code path is not exercised against real platform behavior. Fix: document the invariant (provider teamId must match the platform-assigned team) or relax the personal-mode check to box.teamId === undefined || box.teamId === <personal-team> once a known sentinel exists.

🟠 MEDIUM list() paginates the entire team scope in-memory per call — packages/agent-provider-tangle/src/exact-process.ts

The loop fetches every sandbox in team:<id> or personal scope (100 at a time) and filters by isExactProcessSandbox + metadataMatches in JS, with no upper bound on iterations other than page.length < 100. For a team with thousands of sandboxes this is O(N) network round-trips and O(N) memory on every list() call, and it silently terminates early if the underlying API ever caps page size below 100. Impact: latency and memory blow-up under load; also a billing surface (per-call API quota). Fix: push the metadata and exact-process filters into the list() request when the underlying API supports it, or cap pages and return a cursor.

🟠 MEDIUM Collision-check create() leaks an environment when a buggy provider accepts it — packages/agent-provider-testkit/src/index.ts

The try/catch at lines 151-159 swallows the result of provider.exactProcess.create({...options.createInput, maxLifetimeMs: maxLifetimeMs + 1000}) when a misbehaving provider does NOT reject. If create() resolves, the returned environment is discarded without destroy(), leaking state for the remainder of the conformance run (and confounding the subsequent list/get assertions). Fix: capture the returned env and destroy() it in a finally, or assert it is undefined and treat resolution as the failure (the subsequent assert(collisionRejected, ...) already flags the bug, but the leaked env should still be cleaned up).

🟠 MEDIUM No timeout/abort guard around provider calls; hanging provider hangs the suite — packages/agent-provider-testkit/src/index.ts

An AbortController operation is constructed at line 171 and its signal is passed to writeFile/readFile/spawn, but operation.abort() is never invoked and there is no setTimeout bound on create/wait/status/process.kill. A provider that never resolves spawn() or wait() will hang the conformance suite forever. The launch input has a timeoutMs field, but the testkit does not enforce it nor layer its own wall-clock bound. Fix: add an overall timeout (e.g. setTimeout(() => operation.abort(), options.timeoutMs ?? DEFAULT) cleared on completion) and a guard around create()/wait()/kill().

🟡 LOW Test removes PATH while asserting a different error, masking PATH-check regressions — packages/agent-interface/src/agent-candidate-execution-plan-schema.test.ts

The case overrides launch.env to only { TANGLE_CANDIDATE_TASK_PATH: { value: '/tmp/task.txt' } }, removing PATH for the relative 'node' executable, then asserts toThrow(/fixed evaluator-owned path/). Zod aggregates both issues so the test passes today, but if the PATH superRefine ever short-circuits or its message text changes, the test would still pass because the TANGLE_CANDIDATE_TASK_PATH message still matches. Add an explicit expect(...).rejects.toThrow(/PATH/) variant or preserve PATH in the override so only one contract is exercised.

🟡 LOW Duplicated JSDoc above writeFile orphans the real description — packages/agent-interface/src/environment-provider.ts

Two consecutive /** / blocks sit above writeFile. TypeScript attaches only the immediately-preceding one, so hover/IDE docs show 'Providers must honor the abort signal when supplied.' and the meaningful 'Write exact bytes to an absolute path with a POSIX mode from 0 through 07777.' is orphaned. Merge the two lines into a single /* */ block (or move the abort-sentence into an @param options note).

🟡 LOW Requested egress policy not type-linked to advertised capability modes — packages/agent-interface/src/environment-provider.ts

AgentEnvironmentCapabilities.exactProcess.egress advertises the modes a provider supports (e.g. ['blocked','strict']), and CreateAgentExactProcessEnvironmentInput.egress asks for one policy. Nothing at the type level forces the requested mode to be in the advertised set, and there is no documented 'must throw on unsupported mode' line on AgentExactProcessProvider.create. State the runtime requirement explicitly on create() so a caller can rely on a deterministic error rather than provider-specific behavior.

🟡 LOW stdout()/stderr() replay semantics unspecified on second call — packages/agent-interface/src/environment-provider.ts

Contract says 'Replay buffered UTF-8 stdout, then continue until the process exits.' but does not say whether a second call returns the same buffered content again, throws, or returns an empty iterable. Implementations will diverge. Add one sentence — e.g. 'May only be iterated once per process; subsequent calls throw.' or 'Re-iteration replays the same buffer.' — so providers and consumers agree.

🟡 LOW 'no injected startup environment' is ambiguous — packages/agent-provider-tangle/README.md

The blurb says 'no injected startup environment' but spawn() still forwards launch.env to the process (exact-process.ts:229). The intent is 'no environment auto-injected at sandbox-create time' (secrets:[], no env in exactSandboxOptions), but the wording could be read as forbidding any env on spawned processes. Clarify scope.

🟡 LOW Example references undefined manifestDigest — packages/agent-provider-tangle/README.md

The example interpolates ${manifestDigest} with no preceding declaration. A reader copying this snippet verbatim gets a ReferenceError. Either declare const manifestDigest = '...' above the call or replace with a literal placeholder like <your-image-digest>.

🟡 LOW README example not exercised by a test — packages/agent-provider-tangle/README.md

The README snippet (image digest form, egress: { mode: 'blocked' }, resources, metadata.executionId) is not mirrored in src/index.test.ts as a smoke check. Doc drift risk only — no functional defect.

🟡 LOW README omits teamId option — packages/agent-provider-tangle/README.md

The README shows exactProcess: {} but never documents that TangleExactProcessOptions also accepts teamId?: string, which is required to scope get/list to a team (exact-process.ts:91). Minor discoverability gap for multi-tenant users.

🟡 LOW exact-process shipped in 'files' but not in 'exports' — packages/agent-provider-tangle/package.json

New entries dist/exact-process.{d.ts,js} are added to 'files', so they will be included in the published tarball. However the 'exports' map (lines 9-14 and publishConfig.exports lines 25-32) only exposes '.', so Node's resolver will not allow import ... from "@tangle-network/agent-provider-tangle/exact-process". src/index.ts only re-exports the TangleExactProcessOptions type from "./exact-process.js" ([line 43](https://github.com/tangle-network/agent-sdk/blob/eda63ce96c032d88317a941715c73d3cbb2997ee/pack

🟡 LOW Fresh sandbox that fails attestation is leaked (not destroyed) — packages/agent-provider-tangle/src/exact-process.ts

If client.create() succeeds but the attestation is missing or differs, create() throws without calling box.delete(). The accompanying test asserts deleted === false and frames this as preserving an idempotently recovered environment — but the code cannot distinguish a recovered env from a freshly-created misconfigured one, so a genuine misconfiguration leaks a billed sandbox. Fix: when the platform exposes a provisioned/recovered flag on the create response, only skip deletion in the recovered branch.

🟡 LOW validateExactProcessLaunch rejects empty PATH even though env.PATH is technically a string — packages/agent-provider-tangle/src/exact-process.ts

!input.env.PATH is true for both undefined and the empty string "". An empty PATH (caller explicitly passes PATH: "") is treated identically to no PATH, which forces the executable to be absolute. Probably intentional (no directories to search), but worth surfacing as a documented contract rather than an implicit coercion, since the type Readonly<Record<string,string>> suggests "" is a legal value.

🟡 LOW Capabilities hardcode exactProcess egress modes, overriding caller narrowing — packages/agent-provider-tangle/src/index.ts

When exactProcess is configured, capabilities always returns { egress: ["blocked", "strict"] }, discarding any caller-supplied capabilities.exactProcess value. The guard at line 162 only rejects the contradictory case (exactProcess capability set without the adapter), it never honors a narrower caller capability. Fine for the current adapter (it does enforce both modes), but the silent override is surprising for a caller that thinks it has disabled strict mode. Fix: intersect rather than replace, or document that this provider always supports both.

🟡 LOW Coverage gap: distinct idempotency key creating a distinct environment is not exercised — packages/agent-provider-testkit/src/index.ts

The contract on AgentExactProcessProvider.create (environment-provider.ts:197-200) states 'Repeating the same idempotency key and input returns the same environment. Reusing the key with any different create input must fail.' The testkit verifies both halves of that sentence but never verifies the implicit converse: a NEW idempotency key with the same input must produce a NEW environment (different id). A provider that ignores idempotencyKey entirely and keys only on input would pass the current suite. Recommend one extra create() with a distinct idempotencyKey asserting repeated.id !== environment.id.

🟡 LOW Coverage gap: list() never asserted after spawn() nor after destroy() — packages/agent-provider-testkit/src/index.ts

Line 167 asserts environment.process.list() is empty before spawn (good), and line 236 asserts provider.exactProcess.list({metadata}) returns the env (good). But the testkit never asserts that the spawned process appears in environment.process.list() after spawn() (the contract: 'list(): Promise<AgentExactProcessStatus[]>'), nor that the environment disappears from provider.exactProcess.list() after destroy(). A provider that always returns [] from process.list() would still pass. Recommend asserting list().s

🟡 LOW Double-destroy possible if environment.destroy() throws inside the try body — packages/agent-provider-testkit/src/index.ts

Line 244 await environment.destroy(); precedes destroyed = true; at line 245. If destroy() rejects, destroyed stays false and the finally at line 260 calls destroy() again, masking the original error and potentially triggering provider side-effects on an already-destroying environment. Minor because destroy() should be idempotent by convention, but the contract

🟡 LOW Termination equality via JSON.stringify is order-sensitive — packages/agent-provider-testkit/src/index.ts

Line 211 compares wait() and status().termination via JSON.stringify(...) === JSON.stringify(...). For the AgentCandidateTermination discriminated union (agent-candidate.ts:752-756) this works when both objects are constructed identically, but produces false negatives when the same fields appear in different insertion order across providers (legitimately possible since the type does not mandate key order). Recommend a deep-equal by sorted keys or per-field comparison on kind + kind-specific fields.

🟡 LOW Duplicate @tangle-network/agent-interface versions in dep tree (0.30.0 + 0.31.0) — pnpm-lock.yaml

sandbox@0.11.1 depends on agent-interface@0.30.0 directly AND on agent-core@0.4.19 which depends on agent-interface@0.31.0. Result: two copies of agent-interface resolved in node_modules. If consumer code does instanceof checks, schema identity comparisons, or relies on module-singleton state from agent-interface, behavior can silently split across the two copies. Source is upstream sandbox@0.11.1's own dep declarations, so not fixable in this repo beyond bumping sandbox again later. No action required to merge; flag for awareness.

---

_{tangletools · 2026-07-18T14:29:34Z · trace}

[tangletools]

❌ 2 Blocking Findings — eda63ce9

Full multi-shot audit completed 8/8 planned shots over 19 changed files. Global verifier still owns final merge decision.

Full immutable report for this review: trace

Summary comment for this run: full summary

---

_{tangletools · 2026-07-18T14:29:34Z · immutable trace}

[tangletools]

✅ Auto-approved drewstone PR — 43e614b7

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-07-20T21:27:44Z}

[tangletools]

🟡 Value Audit — sound-with-nits

Verdict	sound-with-nits
Concerns	1 (1 weak-concern)
Heuristic	0.0s
Duplication	0.0s
Interrogation	124.7s (2 bridge agents)
Total	124.7s

💰 Value — sound

Adds an opt-in, shell-free, replace-don't-extend exact-process provider contract plus a Tangle Sandbox adapter and shared lifecycle testkit; coherent with the codebase's optional-capability grain, no existing equivalent to reuse.

• What it does: Defines a new optional AgentExactProcessProvider capability on AgentEnvironmentProvider (packages/agent-interface/src/environment-provider.ts:76-206, 338-342, 361) that exposes an isolated, recoverable, shell-free process environment: idempotent create, explicit resources, blocked/strict egress, absolute-path file I/O with byte-bounded reads, terminal-reason-bearing process status, and kill-id
• Goals it achieves: Give 'approved candidate execution' (which already has declarative schemas in agent-candidate-code-schema.ts and agent-candidate-execution-plan-schema.ts) one provider-neutral runtime contract, so products don't hand-write Sandbox create/process/file/recovery/cleanup logic each time. Once merged, any provider can declare exactProcess, the testkit proves it conforms, and the candidate schemas' PA
• Assessment: Good change, in the grain of the codebase. The optional-capability shape mirrors how AgentEnvironment already surfaces exec/read/write/checkpoint/fork as optional methods, and exactProcess sits as the same kind of opt-in on AgentEnvironmentProvider. The contract is sharply stronger than the existing environment.exec() shell path — it pins immutable images (sha256 digest regex at
• Better / existing approach: none — this is the right approach. Searched packages/ for spawnExact|exactProcess|exact-process|agent:false|runtimeMode.*control and confirmed: no prior wrapper for the Sandbox SDK's control-runtime mode exists in this repo; the three other providers (daytona, e2b, computesdk) only implement the shell-based exec() path and have nothing resembling this; the loose environment.exec() cannot enf
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 2
• Bridge warning: opencode/kimi-for-coding/k2p7: bridge stream ended without value-audit content

🎯 Usefulness — sound-with-nits

A provider-neutral exact-process primitive that wires cleanly into the existing AgentEnvironmentProvider contract, fits the candidate-execution grain, and is robust under realistic edge cases; only minor capacity concern in list pagination.

• Integration: Wires in cleanly as an optional exactProcess property on AgentEnvironmentProvider (environment-provider.ts:361) and an exactProcess capability on AgentEnvironmentCapabilities (environment-provider.ts:339). The Tangle adapter exposes it via opt-in exactProcess: TangleExactProcessOptions in createTangleProvider (packages/agent-provider-tangle/src/index.ts:139,146-152), with a consistency
• Fit with existing patterns: Fits the codebase's grain. It is added as an optional capability alongside the existing agent-backed create() — not competing with it (README:65-70 says so explicitly: 'separate from agent-backed create()'). The Tangle adapter reuses the existing structural types SandboxClientLike / SandboxInstanceLike / SandboxProcessLike (index.ts:40-121) rather than redefining sandbox shapes. The tighte
• Real-world viability: Robust well past the happy path. Validates immutable image digest (regex sha256, exact-process.ts:20-21,122-126), positive integer resources with whole-GiB disk (184-209), whole-second maxLifetime (130-138), non-empty idempotency key and strict-mode allowDomains (149-153). Create failure path deletes the box and aggregates cleanup errors (66-80). Distinguishes process-only sandboxes by BOTH `runti
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

🎯 Usefulness Audit

🟡 List pagination caps at ~2000 environments before throwing [robustness] ``

exact-process.ts:23-24 sets LIST_PAGE_SIZE=1000 and MAX_LIST_OFFSET=1000, so the loop at 90-109 terminates after offset 0 and offset 1000 — ~2000 records — then throws 'Tangle exact process lookup exceeds the Sandbox list pagination limit' (110-112). The contract delegates pagination to the provider (environment-provider.ts:204-205), so this is a deliberate bound, not a bug. But for a measured-candidate execution workload at scale (many concurrent cells per benchmark), exceeding 2000 active exac

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260720T213004Z}