These five documents explain the "why" behind the agent-coordinator architecture. Read them in numerical order (01 → 05) — each builds on the previous.
| # | File | What it covers |
|---|---|---|
| 01 | 01-session-durable-object.md |
SessionDO design: hibernation, private SQLite, WebSocket hub, alarm lifecycle |
| 02 | 02-data-plane-spawn.md |
How Modal sandboxes are spawned: spawnSandbox(), env-var construction, credential chain |
| 03 | 03-supervisor-bootstrap.md |
What runs inside the sandbox: supervisor entrypoint, agent bridge startup, WebSocket dial-back |
| 04 | 04-bridge-communication.md |
Bridge protocol: event types, ackId mechanism, critical-event retry, message queue |
| 05 | 05-prompt-event-flow.md |
End-to-end prompt flow: user message → DO queue → bridge → OpenCode → response → client |
background-agents-architecture.html— vendored upstream reference. Read after 01–05 if you want the original design context.
AGENTS.md— canonical guide (read first)docs/decisions/— active architecture decisionssrc/do/session-do.ts— the implementationsrc/do/sandbox-event-contract.ts— bridge event types