docs(agents): invariant 6 — reuse the engine primitive, don't hand-roll it

[drewstone]

Codifies the architectural smell Drew keeps catching: the shell reinventing an engine capability (paying latency + drift). Before adding any streaming/turn/session/durability primitive, grep the engines + existing exports; a new one needs a written why-existing-doesn't-fit.

Canonical rule: streaming a sandbox agent run to a browser is the sandbox SDK read-only JWT gateway (streamPrompt + lastEventId replay) — never a hand-rolled Durable Object. The /stream turn-buffer + /turn-stream DO are the sandbox-free path only.

Caught instance: gtm-agent (a sandbox product) streams via SessionStreamDO extends TurnStreamDO where the gateway already exists — the smell + extra latency. Fix = migrate gtm to the gateway, then retire TurnStreamDO's streaming role (tracked separately).

Docs-only.

🤖 Generated with Claude Code

[tangletools]

✅ Auto-approved drewstone PR — 17155e4e

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-24T20:44:22Z}

[tangletools]

✅ No Blockers — 17155e4e

Review health 100/100 · Reviewer score 92/100 · Confidence 65/100 · 1 finding (1 low)

glm: Correctness 92 · Security 92 · Testing 92 · Architecture 92

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

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

🟡 LOW Invariant paragraph is dense/long — AGENTS.md

Nit only, not blocking. The new invariant #6 is a single ~6-clause sentence packing the grep-requirement, canonical gateway case, anti-pattern (do-not-hand-roll), scope qualifier (sandbox-FREE ONLY), and a caught-instance anecdote. Consider splitting the canonical-case + anti-pattern into a sub-bullet for scanability, matching the tighter style of invariants 1-5. No correctness impact.

---

_{tangletools · 2026-07-24T20:46:43Z · trace}

[tangletools]

✅ Approved — 1 non-blocking finding — 17155e4e

Full multi-shot audit completed 1/1 planned shots over 1 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-24T20:46:43Z · immutable trace}

[tangletools]

🟡 Value Audit — sound-with-nits

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

💰 Value — sound-with-nits

Docs-only one-liner codifying a real, code-verified architectural rule (grep engines before hand-rolling a streaming/durability primitive); sound and in-grain, but its absolute 'sandbox-FREE path ONLY' phrasing contradicts the shell's own /chat-routes vertical.

• What it does: Adds 'invariant 6' to AGENTS.md: before adding any streaming/turn/session/durability primitive, grep the engines (@tangle-network/sandbox, agent-runtime, agent-eval) AND existing agent-app exports for one that already does it; a new primitive needs a written why-existing-doesn't-fit. Pins the canonical case — streaming a sandbox run to a browser is the sandbox SDK read-only JWT gateway (streamProm
• Goals it achieves: Stop the recurring smell where the shell (or a product on it) reinvents an engine capability and pays latency + drift. The PR body's 'caught instance' is real: src/turn-stream/core.ts:5-6 confirms /turn-stream was extracted from gtm-agent's hand-rolled SessionStreamDO. The goal is to make future authors reach for the gateway / engine primitive first.
• Assessment: Good change on its merits. It extends the existing engine/shell invariant set (1-5 are all about separation) with the specific streaming/durability case Drew keeps catching, and the canonical example is grounded in shipped code. It reinforces (mildly overlaps) principle 4 at AGENTS.md:55 ('Don't rebuild harness or platform primitives') and the session-transport table at AGENTS.md:65, but that is r
• Better / existing approach: Searched src/chat-routes (turn-routes.ts:655-663), src/turn-stream/core.ts, and the AGENTS.md module map + session-transport table. The rule is right; the boundary as written is too absolute. The fix is to sharpen invariant 6 so it targets the actual smell — a PRODUCT hand-rolling a DO to fanout/re-broadcast sandbox session events when the gateway already does browser-direct attach + reconnect rep
• 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

Codifies the recurring engine-primitive smell as a top-level invariant; grounded in real subpaths and consistent with existing doctrine.

• Integration: Documentation only; no code surface to reach. The rule references real subpaths — /turn-stream TurnStreamDO (AGENTS.md:36), the /stream turn-buffer (AGENTS.md:35), and the session-gateway pattern (AGENTS.md:65) — so the invariant points at artifacts that actually exist. It will be read by every agent editing this repo (AGENTS.md is the entry point).
• Fit with existing patterns: Fits cleanly. The five existing invariants are all one-line architectural gates (peer-deps, seam-composition, structural-deps, substrate-free, additive-subpaths); invariant 6 is the same shape and closes the one gap they left (streaming/durability primitives). It echoes agent-native principle 4 (AGENTS.md:55) and the session-transport table (AGENTS.md:65), but elevation is correct: invariants are
• Real-world viability: A doc rule, so happy/edge paths don't apply directly. The substantive test — will it catch the smell it targets — is yes: it names the exact grep targets (sandbox, agent-runtime, agent-eval), the canonical right answer (session-gateway JWT), and the canonical wrong answer (TurnStreamDO for a sandbox product), plus a real caught instance. A contributor hitting this invariant has enough to a
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

💰 Value Audit

🟠 'sandbox-FREE path ONLY' contradicts /chat-routes, which taps the turn-buffer BY DEFAULT with a sandbox producer [against-grain] ``

Invariant 6 (AGENTS.md:20) labels the /stream turn-buffer + /turn-stream DO as the 'sandbox-FREE path ONLY'. But the shell's assembled vertical crosses that line: AGENTS.md:35 documents /chat-routes' 'turn-buffer tap wired BY DEFAULT' with createSandboxChatProducer (a sandbox producer), and src/chat-routes/turn-routes.ts:655-663 implements that durability tap so 'a dropped client replays the tail' — the reconnect-replay job the invariant assigns to the gateway (AGENTS.md:65). /turn-stream itself

---

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 · 20260724T204749Z}