Ch1. Eve Mental Model
Understand Eve as filesystem authoring, durable workflow execution, runtime harness, and channel protocol.
Written and reviewed by Eric Han · Co-founder & CTO, reopt
Key takeaways
- Read Eve as four surfaces: filesystem authoring, compiled manifests, runtime harness, and delivery channels.
- Durable execution is checkpointed as
session -> turn -> step; interrupted steps may rerun. - Enterprise Eve design starts by separating app runtime, sandbox, and channel responsibilities.
The first things you notice in Eve are helpers such as defineAgent, defineTool, and eveChannel. For enterprise design, the more important questions are: what code runs where, what data crosses which boundary, and what can be replayed after failure?
| Surface | Responsibility | Representative files/concepts | Operator question |
|---|---|---|---|
| Authoring | Human-authored agent capability surface | agent/agent.ts, instructions.md, tools/, skills/ | What can the model see and request? |
| Compile | Stable manifest and module-map generation | discoverAgent, compileAgent, .eve/* | What exactly ships? |
| Runtime | A turn-level model/tool loop | resolveRuntimeAgentGraph, ToolLoopAgent, harness | Where do tools, approval, compaction, and dynamic capabilities run? |
| Delivery | External session start/resume/streaming | channels, client SDK, NDJSON stream | Who called the agent and which continuation token is valid? |
Filesystem-first Design
Eve derives identities from paths.
agent/tools/refund_charge.ts -> tool refund_charge
agent/skills/release/SKILL.md -> skill release
agent/connections/linear.ts -> connection linear
agent/subagents/researcher/agent.ts -> subagent researcherThis is useful because review boundaries become obvious. A new file under agent/tools/ is a new executable capability. A file under agent/connections/ is a new external system surface. A subagent directory creates a new delegation unit.
The same property makes naming a governance concern. Tool names, connection names, and subagent names can appear in model traces, evals, approval logs, and prompts. Treat renames as behavior changes.
Durability: Session, Turn, Step
| Unit | Meaning | Design point |
|---|---|---|
| Session | Long-lived conversation or job | History, state, sandbox state, and continuation token survive across turns. |
| Turn | One user input and all work it triggers | Includes model calls, tool calls, and subagent calls. |
| Step | Durable checkpoint unit | A model call plus requested actions are recorded together. |
The key is the step. A completed step does not rerun; its recorded result is replayed. A step interrupted mid-execution can run again. Non-idempotent side effects need one of these safeguards:
- provider idempotency keys
- Eve
approval - an external "already executed" ledger
- separate read-only and write tools, with writes gated
App Runtime vs Sandbox
| Concern | App runtime | Sandbox |
|---|---|---|
process.env | Available | Not available by default |
authored tool execute | Runs here | Does not run here |
| built-in shell/file effects | Proxied | Applied in /workspace |
| secrets | Can be held | Should not be injected |
| network | runtime environment | sandbox network policy |
Custom authored tools run in the app runtime. Built-in shell/file tools operate against the sandbox. This split is the central trust boundary.
| Task type | Recommended Eve surface |
|---|---|
| API call needing secrets | authored tool or connection |
| model-driven code/file work | sandbox built-in tools |
| sensitive external write | tool + approval + audit hook |
| internal data lookup | connection allow-list + least-privilege token |
| long analysis or artifact generation | sandbox workspace + subagent |
Channels Are Not Session Queues
Message sends in 0.82.0 default to turnPolicy: "steer"; select "queue" when the active turn should finish first. Current-caller steering retains durable arrival order and may be folded together at a boundary. Use structured inputResponses to address a pending approval. A new non-answer from that caller can cancel the approval rather than wait behind it.
Keep tenant/session ownership checks above transport authentication. For the current delivery contract, see Sessions, runs, and streaming, rather than treating the early continuationToken implementation as the complete interface.
One Sentence To Keep
Eve is not "a model running code." It is a durable workflow runtime where the model requests capabilities declared as files, and Eve mediates approval, isolation, recording, and resume.
Enterprise Eve Agent Development
A practical enterprise handbook for building high-quality durable AI agents with Vercel Eve, updated for Eve 0.82.0 public APIs, with a historical source atlas.
Ch2. Source Code Atlas
Read packages/eve/src by implementation responsibility and identify the files enterprise reviewers should understand.