# Eve Filesystem Slots & Compiled Artifacts > How Eve treats the agent/ directory as the contract: path-derived identities for tools, skills, channels, and subagents; defineAgent for additive runtime config; and compilation into inspectable .eve/ runtime artifacts. - Repository: vercel/eve-with-withastro-flue - GitHub: https://github.com/vercel/eve - Human wiki: https://www.grok-wiki.com/public/wiki/vercel-eve-with-withastro-flue-43b600348681 - Complete Markdown: https://www.grok-wiki.com/public/wiki/vercel-eve-with-withastro-flue-43b600348681/llms-full.txt ## Source Files - `vercel-eve:docs/reference/project-layout.md` - `vercel-eve:packages/eve/src/compiler/compile-agent.ts` - `vercel-eve:packages/eve/src/compiler/normalize-channel.ts` - `vercel-eve:packages/eve/src/internal/authored-module-loader.ts` - `vercel-eve:apps/frameworks/nuxt/agent/agent.ts` - `vercel-eve:apps/frameworks/nuxt/agent/instructions.md` - `vercel-eve:docs/agent-config.md` ---
Relevant source files The following files were used as context for generating this wiki page: - [vercel-eve/docs/reference/project-layout.md](vercel-eve/docs/reference/project-layout.md) - [vercel-eve/docs/agent-config.md](vercel-eve/docs/agent-config.md) - [vercel-eve/docs/reference/cli.md](vercel-eve/docs/reference/cli.md) - [vercel-eve/packages/eve/src/compiler/compile-agent.ts](vercel-eve/packages/eve/src/compiler/compile-agent.ts) - [vercel-eve/packages/eve/src/compiler/artifacts.ts](vercel-eve/packages/eve/src/compiler/artifacts.ts) - [vercel-eve/packages/eve/src/compiler/normalize-channel.ts](vercel-eve/packages/eve/src/compiler/normalize-channel.ts) - [vercel-eve/packages/eve/src/compiler/normalize-tool.ts](vercel-eve/packages/eve/src/compiler/normalize-tool.ts) - [vercel-eve/packages/eve/src/compiler/normalize-manifest.ts](vercel-eve/packages/eve/src/compiler/normalize-manifest.ts) - [vercel-eve/packages/eve/src/compiler/normalize-agent-config.ts](vercel-eve/packages/eve/src/compiler/normalize-agent-config.ts) - [vercel-eve/packages/eve/src/compiler/workspace-resources.ts](vercel-eve/packages/eve/src/compiler/workspace-resources.ts) - [vercel-eve/packages/eve/src/internal/authored-module-loader.ts](vercel-eve/packages/eve/src/internal/authored-module-loader.ts) - [vercel-eve/packages/eve/src/discover/discover-agent.ts](vercel-eve/packages/eve/src/discover/discover-agent.ts) - [vercel-eve/packages/eve/src/discover/manifest.ts](vercel-eve/packages/eve/src/discover/manifest.ts) - [vercel-eve/packages/eve/src/public/definitions/agent.ts](vercel-eve/packages/eve/src/public/definitions/agent.ts) - [vercel-eve/apps/frameworks/nuxt/agent/agent.ts](vercel-eve/apps/frameworks/nuxt/agent/agent.ts) - [vercel-eve/apps/frameworks/nuxt/agent/instructions.md](vercel-eve/apps/frameworks/nuxt/agent/instructions.md)
# Eve Filesystem Slots & Compiled Artifacts Eve treats the `agent/` directory as a **filesystem contract**: where you place a file determines what it becomes at runtime. You do not declare identities inside `define*` helpers — the compiler derives tool, skill, channel, connection, and subagent names from paths. `agent.ts` is the one exception in spirit: it uses `defineAgent` for **additive** runtime configuration (model, compaction, build options) while identity still comes from the package or directory name. That contract compiles into inspectable artifacts under `.eve/`. Discovery walks the tree without importing modules; compilation loads authored TypeScript, normalizes definitions, and writes JSON manifests plus a module map the runtime imports. Understanding this split — authored slots on disk versus compiled artifacts — is the fastest way to debug "why didn't Eve pick up my file?" and to see exactly what a deployment will load. ## The `agent/` directory as contract Eve builds an agent by walking the filesystem under `agent/`. Each subdirectory is an **authored slot** with fixed semantics. Files outside recognized slots are ignored or diagnosed. ```text my-agent/ ├── package.json ├── agent/ │ ├── agent.ts ← runtime config (defineAgent) │ ├── instructions.md ← system prompt (required at root) │ ├── tools/ ← defineTool modules │ ├── skills/ ← markdown, modules, or packages │ ├── channels/ ← HTTP/messaging entrypoints (root only) │ ├── connections/ ← MCP, OpenAPI, etc. │ ├── hooks/ ← lifecycle subscribers │ ├── schedules/ ← recurring jobs (root only) │ ├── sandbox/ ← sandbox definition + workspace seeds │ ├── lib/ ← import-only helpers (never mounted) │ └── subagents// ← nested agent packages └── evals/ ← sibling of agent/, not inside it ``` Sources: [vercel-eve/docs/reference/project-layout.md:6-63]() | Slot | Identity source | Subagents can author? | Notes | |------|-----------------|----------------------|-------| | `agent.ts` | Package name or app-root basename | Yes | `defineAgent`; optional at root (defaults apply) | | `instructions.*` | Composed at build time | Optional | Required on root agent | | `tools/*.ts` | Path under `tools/` | Yes | Nested dirs flatten to dashed slugs | | `skills/*` | Path under `skills/` | Yes | Seeded to `/workspace/skills/...` | | `channels/*` | Path under `channels/` | No | Root only; routes expand to entries | | `connections/*.ts` | Filename | Yes | One connection per file | | `subagents//` | Directory name `` | Yes | Full nested slot surface | | `lib/` | N/A (not registered) | Yes | Import-only; never reaches workspace | Local subagents under `subagents//` mirror the root layout but **cannot** author `channels/` or `schedules/`. Each child discovers its own slots independently and inherits nothing from the parent. Sources: [vercel-eve/docs/reference/project-layout.md:74-97]() ## Path-derived identity **You never write a `name` or `id` field on a `define*` call.** The compiler strips extensions and slot prefixes to produce stable identities. | Authored path | Resolves to | |---------------|-------------| | `agent/tools/get_weather.ts` | tool `get_weather` | | `agent/tools/billing/refund.ts` | tool `billing-refund` (nested paths flatten) | | `agent/skills/summarize.md` | skill `summarize` | | `agent/connections/linear.ts` | connection `linear` | | `agent/channels/slack.ts` | channel `slack` | | `agent/subagents/researcher/agent.ts` | subagent `researcher` | The root agent id comes from `package.json` `name` (scope stripped), falling back to the app-root directory basename. A local subagent id is its directory name under `subagents/`. Sources: [vercel-eve/docs/reference/project-layout.md:8-19](), [vercel-eve/packages/eve/src/discover/manifest.ts:290-306](), [vercel-eve/packages/eve/src/compiler/normalize-tool.ts:27-51]() Tools are special: path separators cannot reach model providers, so nested tool directories flatten to a single dashed segment. Authored `name` fields on tools are rejected by the normalizer. ```49:51:vercel-eve/packages/eve/src/compiler/normalize-tool.ts const toolName = stripLogicalPathExtension(source.logicalPath) .replace(/^tools\//, "") .replaceAll("/", "-"); ``` Channels derive the channel name from the filesystem path; each route in `defineChannel` becomes a separate compiled entry with its own URL path. ```36:61:vercel-eve/packages/eve/src/compiler/normalize-channel.ts const channelName = stripLogicalPathExtension(source.logicalPath).replace(/^channels\//, ""); // ... return definition.routes.map((route) => ({ kind: "channel" as const, name: channelName, logicalPath: source.logicalPath, method: route.method.toUpperCase() as ChannelRouteMethod, urlPath: route.path, // ... })); ``` ## `defineAgent`: additive runtime config `agent.ts` default-exports `defineAgent({ ... })` from `eve`. The helper is a typed identity function — it returns the definition unchanged while enforcing the `AgentDefinition` shape at compile time. It is **additive**: you configure runtime behavior; you do not set identity. ```33:37:vercel-eve/packages/eve/src/public/definitions/agent.ts export function defineAgent( definition: ExactDefinition, ): TAgent { return definition; } ``` Typical fields include `model`, `modelOptions`, `compaction`, `experimental`, `outputSchema`, and `build.externalDependencies`. When `agent.ts` is absent at the root, Eve applies a default model; when present, `model` is required. A minimal real example from the Nuxt framework demo: ```1:13:vercel-eve/apps/frameworks/nuxt/agent/agent.ts import { defineAgent } from "eve"; export default defineAgent({ model: "anthropic/claude-opus-4.7", modelOptions: { providerOptions: { anthropic: { thinking: { type: "adaptive", display: "summarized" }, effort: "high", }, }, }, }); ``` Adjacent concerns stay in their slots — instructions in `instructions.md`, tools in `tools/`, sandbox in `sandbox/`, auth on channels — not in `defineAgent`. Sources: [vercel-eve/docs/agent-config.md:6-68](), [vercel-eve/packages/eve/src/compiler/normalize-agent-config.ts:25-44]() ## Discovery and compilation pipeline Eve separates **discovery** (filesystem classification, no module imports) from **compilation** (bundle, load, normalize). `compileAgent` orchestrates both and writes `.eve/` artifacts. ```mermaid flowchart TB subgraph authored ["Authored surface (agent/)"] slots["Filesystem slots
tools/, skills/, channels/, …"] agentTs["agent.ts (defineAgent)"] instr["instructions.md"] end subgraph discover ["Discovery (no imports)"] walk["discoverAgent()
walk + classify entries"] srcManifest["agent-discovery-manifest.json"] diag["diagnostics.json"] end subgraph compile ["Compilation (module load + normalize)"] loader["authored-module-loader
Rolldown bundle → .mjs cache"] normalize["compileAgentManifest()
per-slot normalizers"] workspace["materializeWorkspaceResources()"] outManifest["compiled-agent-manifest.json"] moduleMap["module-map.mjs"] end subgraph runtime [".eve/ runtime load"] eveStart["eve dev / eve start"] end slots --> walk agentTs --> walk instr --> walk walk --> srcManifest walk --> diag srcManifest --> normalize normalize --> loader loader --> normalize normalize --> workspace workspace --> outManifest normalize --> moduleMap outManifest --> eveStart moduleMap --> eveStart ``` ### Phase 1: Discovery `discoverAgent` reads sorted directory entries, classifies each against slot grammar, and builds an `AgentSourceManifest` listing source references (logical paths, source ids) plus diagnostics. It never imports authored modules — only filesystem structure matters. ```55:57:vercel-eve/packages/eve/src/discover/discover-agent.ts /** * Discovers the current agent's authored source graph without importing authored * modules. */ ``` Discovery walks each slot in sequence: instructions, `agent.ts`, channels, lib, schedules, connections, sandbox, tools, hooks, skills, and subagents. Sources: [vercel-eve/packages/eve/src/discover/discover-agent.ts:58-196]() ### Phase 2: Compilation `compileAgentManifest` loads each module-backed source through `loadModuleBackedDefinition`, which uses `authored-module-loader` to Rolldown-bundle TypeScript into content-hashed `.mjs` files under `node_modules/.cache/eve/authored-modules/`, then dynamically imports them. Concurrent loads of the same path are deduplicated to avoid bundle races. Per-slot normalizers (`compileToolEntry`, `compileChannelDefinition`, `compileSkillSource`, etc.) validate exports against public Eve shapes and attach path-derived names. Workspace-bound resources (skills, sandbox seeds) are materialized under `.eve/compile/workspace-resources/`. Sources: [vercel-eve/packages/eve/src/compiler/normalize-manifest.ts:31-53](), [vercel-eve/packages/eve/src/internal/authored-module-loader.ts:61-112](), [vercel-eve/packages/eve/src/compiler/workspace-resources.ts:17-29]() ### Phase 3: Artifact write `writeCompilerArtifacts` persists everything under `.eve/`, even when discovery reports errors (so you can inspect partial output). | Artifact | Purpose | |----------|---------| | `.eve/discovery/agent-discovery-manifest.json` | Raw discovery result — what Eve found on disk | | `.eve/discovery/diagnostics.json` | Errors and warnings with source paths | | `.eve/compile/compiled-agent-manifest.json` | Normalized surface the runtime loads | | `.eve/compile/compile-metadata.json` | Schema version, generator info, content hashes, `ready`/`failed` status | | `.eve/compile/module-map.mjs` | Flattened import map for authored module entrypoints | | `.eve/compile/workspace-resources/` | Materialized skill and sandbox seed trees | Sources: [vercel-eve/packages/eve/src/compiler/artifacts.ts:117-136](), [vercel-eve/docs/reference/cli.md:64-72]() `compileAgent` throws `CompileAgentError` when diagnostics contain errors, but artifacts are already written — open `diagnostics.json` to see exactly which file violated the contract. Sources: [vercel-eve/packages/eve/src/compiler/compile-agent.ts:58-85]() ## What reaches the runtime workspace Eve does **not** mount the entire `agent/` tree into the sandbox. Only two authored sources land in the agent workspace at session bootstrap: | Authored source | Runtime path | |-----------------|--------------| | `agent/skills/**` | `/workspace/skills/...` | | `agent/sandbox/workspace/**` | `/workspace/...` | Everything under `lib/` remains import-only source compiled into bundles; it never appears in the workspace. Instructions compose into the system prompt at build time rather than being mounted as files. Sources: [vercel-eve/docs/reference/project-layout.md:65-72]() ## Debugging the contract When a file is not discovered: 1. Run `eve info` — lists the active tools, skills, subagents, routes, and diagnostics. 2. Confirm the file sits in the correct slot per the table above. 3. Check root-vs-subagent boundaries (e.g. `channels/` and `schedules/` are root-only). 4. Open `.eve/discovery/diagnostics.json` for shape errors on `define*` exports. Artifacts are preserved on partial failure, so a failed `eve build` still leaves a inspectable snapshot of what discovery found and where normalization broke. Sources: [vercel-eve/docs/reference/project-layout.md:114-116](), [vercel-eve/docs/reference/cli.md:62-72]() ## Summary Eve's agent authoring model is **convention over configuration**: the `agent/` directory layout is the contract, path-derived identities replace inline `name` fields, and `defineAgent` adds runtime config without changing identity. Discovery classifies the filesystem; compilation bundles and normalizes modules into `.eve/` artifacts that the runtime imports verbatim. Treat `.eve/` as the ground truth for what a running agent actually loads — especially when debugging discovery misses or comparing local builds to deployments.