Ch1. Eve Mental Model
Understand Eve as filesystem authoring, durable workflow execution, runtime harness, and channel protocol.
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
needsApproval - 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
continuationToken is a resume handle for the current session hook. It is not a general FIFO queue address. If multiple messages hit the same session concurrently, deterministic chat ordering is an application/channel concern.
| Situation | Design |
|---|---|
| Slack or Teams burst input | Maintain a per-session queue in the channel/app layer. |
| Approval click and a new message arrive together | Resolve the approval first and defer the message to the next step. |
| Batch jobs submit many requests | Split sessions or use an app-level job queue. |
| Tenant-specific ownership is required | Implement session ownership ACLs above route auth. |
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, based on Eve 0.11.4 source and the full official docs corpus.
Ch2. Source Code Atlas
Read packages/eve/src by implementation responsibility and identify the files enterprise reviewers should understand.