From 17155e4ecf70b4f2f05e166e42c5c6c542249695 Mon Sep 17 00:00:00 2001 From: Drew Stone Date: Fri, 24 Jul 2026 14:44:11 -0600 Subject: [PATCH] =?UTF-8?q?docs(agents):=20invariant=206=20=E2=80=94=20reu?= =?UTF-8?q?se=20the=20engine=20primitive,=20don't=20hand-roll=20it?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codifies the recurring architectural smell: the shell reinventing an engine capability and paying latency + drift for it. Before adding any streaming / turn / session / durability primitive, grep the engines + existing exports for one that already does it; a new primitive needs a written why-existing-doesn't-fit. Canonical case: streaming a sandbox agent run to a browser IS the sandbox SDK's read-only JWT session gateway — never a hand-rolled Durable Object. The /stream turn-buffer + /turn-stream DO are the sandbox-FREE path only. (Caught instance: a fleet app streaming a sandbox turn through a hand-rolled TurnStreamDO.) --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 9c5bcee..d05b786 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,7 @@ Corollary — **extend, never duplicate.** Before writing anything that complete 3. **Structural over hard-dep where possible.** `/tangle` and `/billing` take the tcloud client as a structural contract (no tcloud dep). Prefer that to a dep when the surface is small. 4. **Substrate-free is a feature.** `/runtime`, `/web`, `/crypto`, `/redact` import nothing — they're pure mechanism behind callback seams. Keep them that way. 5. **Additive subpaths.** New capability = new `./subpath` (entry in `tsup.config.ts` + `exports` in `package.json` + root barrel). Never a breaking change to an existing export. +6. **Reuse the engine primitive; never hand-roll one the engine already gives you.** 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 requires a written "why every existing one doesn't fit" — no exceptions. The recurring smell is the shell reinventing an engine capability and paying latency + drift for it. **Canonical case: streaming a sandbox agent run to a browser is the sandbox SDK's read-only JWT session gateway (`streamPrompt` + `lastEventId` replay) — durable replay + reconnect, browser-direct, lowest latency.** Do NOT hand-roll a Durable Object or the `/stream` turn-buffer to re-broadcast a sandbox session's turn events; the `/stream` turn-buffer + `/turn-stream` DO are the **sandbox-FREE path ONLY** (a copilot streaming its own runtime, where no sandbox session exists to attach to). Using them for a sandbox product is the smell (a caught instance: a fleet app streaming a sandbox turn through a hand-rolled `TurnStreamDO` instead of the gateway). ## Module map