Ch2. Source Code Atlas
Read packages/eve/src by implementation responsibility and identify the files enterprise reviewers should understand.
Key takeaways
packages/eve/srcis easiest to read as public API, discovery/compiler, runtime/harness, and execution layers.- Discovery and compilation turn authored files into manifests before runtime execution.
- Enterprise review should focus on runtime graph assembly, tool registry construction, and durable execution behavior.
This chapter is a map for reading Eve 0.11.4 source. The codebase is broad, but the responsibility split is clear.
Directory Responsibilities
| Directory | Responsibility | Why it matters |
|---|---|---|
public/ | User-facing APIs and framework integrations | Defines authoring contracts. |
discover/ | Scans agent/ file slots | Determines which files become capabilities. |
compiler/ | Builds compiled manifests and module maps | Defines deployable artifacts. |
runtime/ | Hydrates compiled graph into registries | Merges defaults, authored files, subagents, hooks, sandbox. |
harness/ | Runs one turn's model/tool loop | Controls compaction, tool execution, HITL, model IO. |
execution/ | Durable session/turn/step driver | Governs checkpointing, park/resume, replay. |
evals/ | Evaluation runner and assertions | Drives real HTTP/session surfaces. |
cli/ | eve init, build, dev, eval, etc. | Operator entrypoints. |
Public API Starts In public/
packages/eve/src/public/index.ts exports the primary helpers. Nested public paths expose tools, connections, channels, sandbox, evals, hooks, instrumentation, and framework bindings.
Review point: public helpers are the contract that authored files rely on. When upgrading Eve, compare exported helpers and types before changing production agents.
Discovery And Compiler Do Not Trust Authored Modules
Discovery reads file paths, extensions, directories, and static metadata. It does not execute arbitrary authored tool code. The compiler then writes .eve/ artifacts and diagnostics.
| File | What to check |
|---|---|
discover/project.ts | Flat vs nested project resolution |
discover/discover-agent.ts | Slot discovery and subagent discovery |
compiler/compile-agent.ts | Artifact writes and diagnostic failures |
compiler/manifest.ts | Compiled manifest schema/version |
The enterprise value is release evidence: .eve/diagnostics.json, discovery manifests, compiled manifests, and module maps show what the agent really contains.
Runtime Builds The Agent Graph
Runtime graph resolution combines:
- framework default tools and channels
- authored overrides and disabled defaults
- authored tools, skills, instructions, hooks, schedules, sandbox
- connections and connection tools
- subagents and remote agents
- dynamic capabilities
The model-visible tool surface is not just agent/tools/. It is the merged registry.
Harness Runs The Turn
The harness is where model calls, tool calls, provider options, compaction, approval, and stream events meet.
| Concern | Source area |
|---|---|
| Tool loop | harness/tool-loop.ts |
| ToolSet assembly | harness/tools.ts |
| Message conversion | harness/messages.ts |
| HITL requests | harness/input-requests.ts |
| Tool execution | harness/execute-tool.ts |
Review point: every privileged authored tool should be evaluated as an app-runtime execution surface, not a sandboxed action.
Execution Is The Durable Driver
execution/ shows why Eve durability is more than retry. The session snapshot, stream events, input requests, continuation tokens, and step results move through durable workflow steps.
| File | Role |
|---|---|
workflow-entry.ts | Session workflow entry and park/resume |
turn-workflow.ts | Turn dispatch contract |
workflow-steps.ts | Step-level harness execution |
durable-session-store.ts | Session snapshots and migration-aware state |
session.ts | Session hydration and compaction config |
Enterprise Code Review Lens
| Surface | Review question |
|---|---|
agent/tools/** | Does it have schema, redaction, idempotency, approval, and audit? |
agent/connections/** | Are token scope, allow/block filters, and approval correct? |
agent/channels/** | Does route auth differ from session ownership ACL? |
agent/sandbox/** | Is network egress explicit and are secrets absent from workspace? |
agent/subagents/** | Does delegation reduce authority or accidentally expand it? |
.eve/* artifacts | Do compiled outputs match the intended capability set? |