Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
drewstone merged 1 commit into from
Jul 24, 2026
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down