# Eve

Eve is a filesystem-first framework for durable backend agents on Vercel.

You author an agent as a directory on disk. The directory is the contract — markdown for the parts a human should read like a spec, TypeScript for the parts that benefit from real types and runtime behavior.

The framework is called Eve. The published npm package is `eve`. The CLI binary is `eve`.

## What Eve Prioritizes

- Markdown-first authoring for instructions and procedures
- TypeScript where typed runtime behavior matters
- Durable message runs and follow-up turns
- Inspectable compiled artifacts under `.eve/`
- Per-agent sandbox with optional authored overrides
- A stable HTTP protocol with explicit `continuationToken` and `sessionId` contracts
- A runtime model that keeps channels, harnesses, and workflow execution separate

## Authored Directory

```text
my-agent/
├── package.json
├── tsconfig.json
└── agent/
    ├── agent.ts           # additive runtime config (model, name, build, compaction, …)
    ├── instructions.md    # always-on instructions prompt
    ├── tools/             # typed executable integrations
    ├── skills/            # optional named procedures the model can load on demand
    ├── hooks/             # lifecycle and stream-event subscribers
    ├── channels/          # message ingress and delivery (HTTP, Slack, …)
    ├── connections/       # external MCP server connections
    ├── sandbox/           # the agent's single sandbox (optional override)
    ├── workspace/         # files seeded into the sandbox on each session
    ├── subagents/         # specialist child agents (reuse `defineAgent`)
    ├── schedules/         # recurring jobs
    └── lib/               # shared authored code imported by other files
```

## Authoring Helpers

Every authored directory has a typed helper. Import each from the matching subpath:

| Helper                                                                                                              | Subpath                               | Authored Location                                |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------ |
| `defineAgent(...)`                                                                                                  | `eve`                                 | `agent.ts`, `subagents/<id>/agent.ts`            |
| `defineInstructions(...)`                                                                                           | `eve/instructions`                    | `instructions.ts` (or `instructions.md`)         |
| `defineTool(...)`, `defineBeveTool(...)`, `defineReadFileTool(...)`, `defineWriteFileTool(...)`, `disableTool(...)` | `eve/tools`                           | `tools/<name>.ts`                                |
| `defineSkill(...)`, `getSkill(...)`                                                                                 | `eve/skills`                          | `skills/<name>.ts` (or `skills/<name>.md`)       |
| `defineHook(...)`                                                                                                   | `eve/hooks`                           | `hooks/<slug>.ts`                                |
| `defineChannel(...)`, `POST`, `GET`                                                                                 | `eve/channels`                        | `channels/<name>.ts`                             |
| `eveChannel(...)`, `slackChannel(...)`, `vercelOidc(...)`                                                           | `eve/channels/eve`, `/slack`, `/auth` | reused from `channels/<name>.ts`                 |
| `defineSandbox(...)`                                                                                                | `eve/sandbox`                         | `sandbox.ts` (or `sandbox/sandbox.ts`)           |
| `defineSchedule(...)`                                                                                               | `eve/schedules`                       | `schedules/<name>.ts` (or `schedules/<name>.md`) |
| `defineEval(...)`                                                                                                   | `eve/evals`                           | `evals/<name>.eval.ts`                           |

Runtime accessors live on the subpath that owns the concern:

- `getSession()` — current session, turn, auth, parent lineage (`eve/context`)
- `getSandbox()` — live sandbox handle for the current agent (`eve/sandbox`)
- `getSkill(identifier)` — handle for a named skill visible to the current agent (`eve/skills`)
- `getContext(key)`, `requireContext(key)`, `hasContext(key)`, `setContext(key)`, `ensureContext(key, factory)` — unified context helpers (`eve/context`)

The complete API reference, including types and lower-level runtime primitives, is in [`./dist/docs/public/reference/typescript-api.md`](./dist/docs/public/reference/typescript-api.md).

## Tiny Example

`agent/instructions.md`

```md
You are a weather-focused assistant. Be concise, accurate, and explicit when you use a tool.
```

`agent/tools/get_weather.ts`

```ts
import { defineTool } from "eve/tools";
import { z } from "zod";

export default defineTool({
  description: "Get the current weather for a city.",
  inputSchema: z.object({
    city: z.string(),
  }),
  async execute(input) {
    return {
      city: input.city,
      condition: "Sunny",
      temperatureF: 72,
    };
  },
});
```

`agent/agent.ts`

```ts
import { defineAgent } from "eve";

export default defineAgent({
  model: "openai/gpt-5.4-mini",
});
```

## Quick Start

```bash
pnpm create eve@beta
cd my-agent
pnpm dev
```

The wizard scaffolds the project, picks a model, and (for the REPL channel) installs dependencies and starts the dev server for you. To scaffold into the current empty directory, run `pnpm create eve@beta .`.

CLI commands:

- `eve info` — discovery results and compiled artifacts
- `eve build` — compile `.eve/` and build the host output
- `eve start` — serve the built `.output/` app
- `eve dev` — start the local runtime and REPL

## Deploying

Eve is built for Vercel. The runtime is Nitro + Vercel Workflows. Read [`./dist/docs/public/advanced/deployment.md`](./dist/docs/public/advanced/deployment.md) for the deployment path, environment variables, and Vercel-specific configuration.

## Read Next

These files ship inside the installed package at `node_modules/eve/dist/docs/public/`:

- [Full docs index](./dist/docs/public/README.md) — recommended entry point
- [Getting Started](./dist/docs/public/getting-started.mdx) — install, scaffold, and run locally
- [Project Layout](./dist/docs/public/reference/project-layout.md) — every authored directory in depth
- [`agent.ts`](./dist/docs/public/agent-config.md) — agent config reference
- [TypeScript API](./dist/docs/public/reference/typescript-api.md) — complete `define*` and runtime helper reference
- [Vercel Deployment](./dist/docs/public/advanced/deployment.md) — deploy to production

By authoring concern: [Tools](./dist/docs/public/tools.mdx) · [Channels](./dist/docs/public/channels/overview.mdx) · [Hooks](./dist/docs/public/advanced/hooks.md) · [Skills](./dist/docs/public/skills.mdx) · [Sandbox](./dist/docs/public/sandbox.mdx) · [Connections](./dist/docs/public/connections.mdx) · [Subagents](./dist/docs/public/subagents.mdx) · [Schedules](./dist/docs/public/schedules.mdx) · [Evals](./dist/docs/public/advanced/evals.md)

By runtime concern: [Sessions and Streaming](./dist/docs/public/advanced/sessions-runs-and-streaming.md) · [Session Context](./dist/docs/public/advanced/session-context.md) · [Context Control](./dist/docs/public/advanced/context-control.md) · [Auth and Route Protection](./dist/docs/public/advanced/auth-and-route-protection.md) · [CLI, Build, and Debugging](./dist/docs/public/reference/cli.md) · [Instrumentation](./dist/docs/public/advanced/instrumentation.md)

## Architecture (Internals)

You do not need this section to author an Eve agent — it documents the public HTTP protocol contracts so Eve composes predictably with other systems.

Eve's internal split is:

- the **channel** normalizes inbound transport, applies auth and delivery policy, and owns `continuationToken`
- the **harness** does one unit of AI work and returns `{ session, next }`
- the **runtime** persists state, follows `next`, streams events, and owns workflow primitives (`start()`, `resumeHook()`, `createHook()`, `getWritable()`)

That split is why the public HTTP protocol separates two distinct identifiers:

- `continuationToken` — channel-owned handle the caller uses to start the next user turn
- `sessionId` — runtime-owned handle for streaming and inspection

## Changelog

See [`./CHANGELOG.md`](./CHANGELOG.md) for the release history. The changelog ships inside the published package so agents can read it directly from `node_modules/eve/CHANGELOG.md` to evaluate upgrades.
