eve 0.5.4 → 0.6.0-beta.3

package/dist/docs/public/frontend/sveltekit.mdx

@@ -0,0 +1,94 @@
+---
+title: "SvelteKit"
+description: "Run an Eve agent and a SvelteKit app as one project with the eveSvelteKit Vite plugin."
+---
+
+`eve/sveltekit` lets you run a SvelteKit frontend and an Eve agent as one project instead of two services you have to keep in sync. The `eveSvelteKit()` Vite plugin puts both on one dev server and one Vercel deploy, and [`useEveAgent`](./use-eve-agent-svelte) finds the mounted routes on its own. No CORS config, no URL env vars.
+
+## Register the Vite plugin
+
+Add `eveSvelteKit()` before `sveltekit()`:
+
+```ts title="vite.config.ts"
+import { sveltekit } from "@sveltejs/kit/vite";
+import { eveSvelteKit } from "eve/sveltekit";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [eveSvelteKit(), sveltekit()],
+});
+```
+
+The plugin looks for an `agent/` folder in the SvelteKit project root. Pass `eveRoot` when the agent lives elsewhere:
+
+```ts
+export default defineConfig({
+  plugins: [
+    eveSvelteKit({
+      eveRoot: "../my-agent",
+    }),
+    sveltekit(),
+  ],
+});
+```
+
+## Call the binding
+
+With the plugin in `vite.config.ts`, components call [`useEveAgent`](./use-eve-agent-svelte) from `eve/svelte` and don't pass a host:
+
+```svelte
+<script lang="ts">
+  import { useEveAgent } from "eve/svelte";
+
+  const agent = useEveAgent();
+  let message = $state("");
+  let isBusy = $derived(agent.status === "submitted" || agent.status === "streaming");
+
+  async function handleSubmit() {
+    const text = message.trim();
+    if (!text || isBusy) return;
+    message = "";
+    await agent.send({ message: text });
+  }
+</script>
+
+<form onsubmit={(event) => {
+  event.preventDefault();
+  void handleSubmit();
+}}>
+  <input bind:value={message} disabled={isBusy} />
+  <button type="submit" disabled={isBusy}>Send</button>
+</form>
+```
+
+Out of the box the plugin uses a framework default channel. To set the route auth policy yourself, add `agent/channels/eve.ts` and swap `none()` for a helper like `vercelOidc()` on protected apps. See [Channels](../channels/overview) and [Auth & route protection](../advanced/auth-and-route-protection).
+
+## Dev vs deploy topology
+
+- **Local dev.** `pnpm dev` boots the Eve dev server next to SvelteKit and proxies the Eve routes to it, so the browser only ever hits the SvelteKit origin. `pnpm build && pnpm preview` behaves the same: the preview server gets its own Eve route proxy and either reuses the shared Eve server or starts one.
+- **Vercel.** The SvelteKit app and the Eve runtime deploy as a single project. The web app is public; the Eve runtime sits behind it on the same origin. Use `eveBuildCommand` for a project-specific agent build:
+
+  ```ts
+  export default defineConfig({
+    plugins: [
+      eveSvelteKit({
+        eveBuildCommand: "pnpm build:eve",
+      }),
+      sveltekit(),
+    ],
+  });
+  ```
+
+- **Non-Vercel hosts.** When the Eve service runs on a separate origin, pass `host` directly to `useEveAgent`:
+
+  ```ts
+  const agent = useEveAgent({
+    host: "https://agent.example.com",
+  });
+  ```
+
+## What to read next
+
+- [`useEveAgent` (Svelte)](./use-eve-agent-svelte): the binding API
+- [Auth & route protection](../advanced/auth-and-route-protection)
+- [Deployment](../advanced/deployment)

package/dist/docs/public/frontend/use-eve-agent-svelte.mdx

@@ -0,0 +1,111 @@
+---
+title: "useEveAgent (Svelte)"
+description: "Svelte 5 binding that drives an Eve agent session from the browser."
+---
+
+`useEveAgent()` from `eve/svelte` is the browser side of an Eve session in a Svelte 5 app. Call it once and you get a long-lived session you can send turns to, with every stream event projected into rune-friendly reactive data. On SvelteKit, the [Vite plugin](./sveltekit) wires up the routes. The [frontend overview](./overview) covers the model shared across frameworks.
+
+## Basic usage
+
+Import from `eve/svelte` and read the reactive getters directly. No `$` prefix:
+
+```svelte
+<script lang="ts">
+  import { useEveAgent } from "eve/svelte";
+
+  const agent = useEveAgent();
+</script>
+
+{#each agent.data.messages as message}
+  <p>{message.role}: {JSON.stringify(message.parts)}</p>
+{/each}
+```
+
+## What it returns
+
+| Property  | Type                 | Description                                                               |
+| --------- | -------------------- | ------------------------------------------------------------------------- |
+| `data`    | `TData`              | Projected state. With the default reducer, `EveMessageData` (`messages`). |
+| `status`  | `UseEveAgentStatus`  | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
+| `error`   | `Error \| undefined` | Last transport-level error.                                               |
+| `events`  | `readonly ...[]`     | Raw server events for this session.                                       |
+| `session` | `SessionState`       | Snapshot of session state.                                                |
+| `send`    | `(input) => Promise` | Send text or a full turn (multi-part, attachments, HITL responses).       |
+| `stop`    | `() => void`         | Abort the in-flight request.                                              |
+| `reset`   | `() => void`         | Clear state and start a new session.                                      |
+
+These state fields are reactive getters, so read them straight from templates, `$derived`, or `$effect`. They are not stores, so don't prefix them with `$`.
+
+## Send a message
+
+```svelte
+<script lang="ts">
+  import { useEveAgent } from "eve/svelte";
+
+  const agent = useEveAgent();
+  let message = $state("");
+
+  async function handleSubmit() {
+    const text = message.trim();
+    if (!text) return;
+    message = "";
+    await agent.send({ message: text });
+  }
+</script>
+
+<form onsubmit={(event) => {
+  event.preventDefault();
+  void handleSubmit();
+}}>
+  <input bind:value={message} placeholder="Type a message..." />
+  <button type="submit">Send</button>
+</form>
+```
+
+When a turn is more than plain text, reach for `send()`. Attachments follow the AI SDK `UserContent` format:
+
+```ts
+await agent.send({
+  message: [
+    { type: "text", text: "Describe this image." },
+    { type: "file", data: fileBytes, mediaType: "image/png" },
+  ],
+});
+```
+
+## Human-in-the-loop prompts
+
+A tool opts into approval with `needsApproval` ([Tools](../tools)). When one fires, the pending request rides along on a `dynamic-tool` part of the latest message. Read it, then answer with `agent.send({ inputResponses })`. This find-and-answer flow is identical across frameworks, so the full example lives in the [Frontend overview](./overview#human-in-the-loop-prompts).
+
+## Stop, reset, and resume
+
+`stop()` aborts the in-flight stream. `reset()` wipes state and starts a fresh session. To resume across reloads, hand `initialSession` the state you saved earlier and use `onSessionChange` to persist the cursor as it advances:
+
+```ts
+const agent = useEveAgent({
+  initialSession: savedSessionState,
+  initialEvents: savedEvents,
+  onSessionChange: (session) => {
+    localStorage.setItem("eve-session", JSON.stringify(session));
+  },
+});
+```
+
+## Custom host and credentials
+
+Point `host` at an Eve server on a different origin, and pass credentials through `auth` or `headers`. When you supply a function, it re-resolves before every request:
+
+```ts
+const agent = useEveAgent({
+  host: "https://agent.example.com",
+  headers: async () => ({
+    authorization: `Bearer ${await getAccessToken()}`,
+  }),
+});
+```
+
+## What to read next
+
+- [SvelteKit](./sveltekit): Vite plugin setup
+- [Frontend overview](./overview): the shared integration model
+- [Sessions, runs & streaming](../advanced/sessions-runs-and-streaming)

package/dist/docs/public/frontend/use-eve-agent-vue.mdx

@@ -0,0 +1,123 @@
+---
+title: "useEveAgent (Vue)"
+description: "Vue composable that drives an Eve agent session from the browser."
+---
+
+`useEveAgent()` from `eve/vue` is how a Vue app talks to an Eve session. It opens a long-lived session and sends turns, and it folds every stream event into reactive data you can bind in a template. Nuxt auto-imports it through the [module](./nuxt), and the [frontend overview](./overview) covers the shared model.
+
+## Basic usage
+
+Import the composable from `eve/vue`. Its state is exposed as `ComputedRef`s, so you read it unwrapped in templates:
+
+```vue
+<script setup lang="ts">
+import { useEveAgent } from "eve/vue";
+
+const { data } = useEveAgent();
+</script>
+
+<template>
+  <div v-for="message in data.messages" :key="message.id">
+    <p>{{ message.role }}: {{ message.parts }}</p>
+  </div>
+</template>
+```
+
+## What it returns
+
+| Property  | Type                              | Description                                                               |
+| --------- | --------------------------------- | ------------------------------------------------------------------------- |
+| `data`    | `ComputedRef<TData>`              | Projected state. With the default reducer, `EveMessageData` (`messages`). |
+| `status`  | `ComputedRef<UseEveAgentStatus>`  | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
+| `error`   | `ComputedRef<Error \| undefined>` | Last transport-level error.                                               |
+| `events`  | `ComputedRef<...>`                | Raw server events for this session.                                       |
+| `session` | `ComputedRef<SessionState>`       | Snapshot of session state.                                                |
+| `send`    | `(input) => Promise`              | Send text or a full turn (multi-part, attachments, HITL responses).       |
+| `stop`    | `() => void`                      | Abort the in-flight request.                                              |
+| `reset`   | `() => void`                      | Clear state and start a new session.                                      |
+
+The first five are `ComputedRef`s; the rest are methods. Destructure whatever you need: refs keep their reactivity through destructuring. Read them with `.value` in `<script>`, and unwrapped in `<template>`.
+
+## Send a message
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { useEveAgent } from "eve/vue";
+
+const { send } = useEveAgent();
+const message = ref("");
+
+async function handleSubmit() {
+  const text = message.value.trim();
+  if (!text) return;
+  message.value = "";
+  await send({ message: text });
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <input v-model="message" placeholder="Type a message..." />
+    <button type="submit">Send</button>
+  </form>
+</template>
+```
+
+For anything beyond plain text, reach for `send()`. Attachments follow the AI SDK `UserContent` format:
+
+```vue
+<script setup lang="ts">
+import { useEveAgent } from "eve/vue";
+
+const { send } = useEveAgent();
+
+async function onFileChange(event: Event) {
+  const file = (event.target as HTMLInputElement).files?.[0];
+  if (!file) return;
+  await send({
+    message: [
+      { type: "text", text: "Describe this image." },
+      { type: "file", data: new Uint8Array(await file.arrayBuffer()), mediaType: file.type },
+    ],
+  });
+}
+</script>
+```
+
+## Human-in-the-loop prompts
+
+A tool opts into approval with `needsApproval` ([Tools](../tools)). When it triggers, the pending request shows up as a `dynamic-tool` part on the latest message. Read it and answer with `send({ inputResponses })`. That find-and-answer flow is the same across every framework, so the full example lives in the [Frontend overview](./overview#human-in-the-loop-prompts).
+
+## Stop, reset, and resume
+
+`stop()` aborts the in-flight stream. `reset()` wipes state and starts a fresh session. To survive a reload, pass `initialSession` to restore a saved session and `onSessionChange` to persist the cursor as it moves:
+
+```ts
+const agent = useEveAgent({
+  initialSession: savedSessionState,
+  initialEvents: savedEvents,
+  onSessionChange: (session) => {
+    localStorage.setItem("eve-session", JSON.stringify(session));
+  },
+});
+```
+
+## Custom host and credentials
+
+When your Eve server lives somewhere other than the same origin, point at it with `host` and attach credentials through `auth` or `headers`. Pass a function and it re-resolves before each request:
+
+```ts
+const agent = useEveAgent({
+  host: "https://agent.example.com",
+  headers: async () => ({
+    authorization: `Bearer ${await getAccessToken()}`,
+  }),
+});
+```
+
+## What to read next
+
+- [Nuxt](./nuxt): module setup
+- [Frontend overview](./overview): the shared integration model
+- [Sessions, runs & streaming](../advanced/sessions-runs-and-streaming)

package/dist/docs/public/getting-started.mdx

@@ -0,0 +1,176 @@
+---
+title: "Getting Started"
+description: "Install Eve, scaffold your first agent, give it a tool, and run it locally."
+---
+
+Eve is a filesystem-first framework for durable agents: you write capabilities under `agent/`, and Eve runs the model loop, persists every session, and serves the agent over HTTP and platform channels. This guide gets a small app running locally and walks the current request loop end to end: build, run, message, stream, and follow up.
+
+## Prerequisites
+
+- Node `24.x`
+- `pnpm`
+
+You also need a model credential. Set the provider or gateway key your model string requires (gateway ids like `anthropic/claude-opus-4.8` route through the Vercel AI Gateway), or link a Vercel project that supplies one.
+
+## Create Your Agent
+
+The fastest path is the `create` CLI. It scaffolds the project, prompts for a model, and wires up an optional channel:
+
+```bash
+pnpm create eve@beta
+```
+
+The wizard asks for a model and which channel you want (Web Chat or Slack). You can skip both: every app ships the built-in HTTP channel (`agent/channels/eve.ts`) regardless. For a local chat it installs dependencies and starts the dev server for you.
+
+To add Eve to an existing app instead:
+
+```bash
+pnpm add -D eve
+```
+
+## What's In Your Project
+
+The scaffold writes two files; you add tools as you need them.
+
+`agent/instructions.md` (generated) is the always-on system prompt:
+
+```md
+You are a concise assistant. Use tools when they are available.
+```
+
+`agent/agent.ts` (generated; model comes from the wizard) holds runtime config:
+
+```ts
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: "anthropic/claude-opus-4.8",
+});
+```
+
+Even at this size the agent can already do real work. The default harness gives it file, shell, web, and delegation tools out of the box. See [Default harness](./advanced/default-harness) for the full set and how to override or disable any of them.
+
+### Add Your First Tool
+
+Whatever you name the file becomes the tool name the model sees. Create `agent/tools/get_weather.ts`:
+
+```ts
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+// The runtime tool name comes from the filename, so the model sees this as
+// `get_weather`. Tool filenames must be snake_case ASCII.
+export default defineTool({
+  description: "Get the current weather for a city.",
+  inputSchema: z.object({ city: z.string().min(1) }),
+  async execute({ city }) {
+    return { city, condition: "Sunny", temperatureF: 72 };
+  },
+});
+```
+
+Tools run in your app runtime with full `process.env`, not inside the [sandbox](./sandbox). More in [Tools](./tools).
+
+## Run The App
+
+From the app root:
+
+```bash
+pnpm dev
+```
+
+Useful commands:
+
+- `eve info`: show the active routes and compiled artifacts
+- `eve build`: compile the agent into `.eve/` and build the host output
+- `eve start`: serve the built output
+- `eve dev`: start the local runtime and open the interactive [terminal UI](./advanced/dev-tui)
+
+In the dev TUI, type a message and watch it happen in order: the `get_weather` call, its result, then the reply.
+
+The same CLI can point at a deployment. `eve dev https://your-app.vercel.app` drives a deployed app, which is handy for preview and production smoke tests. See [Deployment](./advanced/deployment).
+
+## Send A Message
+
+Every Eve app exposes the same stable HTTP API. Start a durable session:
+
+```bash
+curl -X POST http://127.0.0.1:3000/eve/v1/session \
+  -H 'content-type: application/json' \
+  -d '{"message":"What is the weather in Brooklyn?"}'
+```
+
+The response comes back with two things you'll reuse:
+
+- a `continuationToken` in the JSON body, to resume this conversation
+- an `x-eve-session-id` header that identifies the run to stream
+
+## Stream The Session
+
+Attach to the session stream:
+
+```bash
+curl http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream
+```
+
+The stream is NDJSON. Expect lifecycle events such as:
+
+- `session.started`
+- `turn.started`
+- `message.received`
+- `step.started`
+- `actions.requested`
+- `action.result`
+- `subagent.called`
+- `subagent.completed`
+- `reasoning.appended`
+- `reasoning.completed`
+- `message.appended`
+- `message.completed`
+- `step.completed`
+- `turn.completed`
+- `session.waiting`
+- `session.completed`
+- `session.failed`
+
+`reasoning.appended` and `message.appended` are optional live-streaming events. Clients that can't surface incremental output can ignore them and rely on `reasoning.completed` and `message.completed`.
+
+`message.completed.data.finishReason` tells you whether assistant text is interim tool-call narration or a terminal reply, and `step.completed.data.usage` carries token usage. When a parent delegates to a subagent, `subagent.called.data.childSessionId` gives you the child session id, so you can subscribe to that child stream and watch the delegated work.
+
+## Send A Follow-Up Message
+
+When the session is waiting for the next user message, post a follow-up with the token:
+
+```bash
+curl -X POST http://127.0.0.1:3000/eve/v1/session/<sessionId> \
+  -H 'content-type: application/json' \
+  -d '{"continuationToken":"<token>","message":"Now do Queens."}'
+```
+
+See [Sessions, runs & streaming](./advanced/sessions-runs-and-streaming) for the full contract.
+
+## Setting up with a coding agent
+
+If a coding agent (Claude Code, Cursor, and the like) is doing the setup, hand it this prompt:
+
+<CopyPrompt text="Set up an Eve agent for the user. Eve is a filesystem-first TypeScript framework for durable agents, published as the npm package eve. Read its docs: once eve is installed they are bundled in the package at node_modules/eve/dist/docs/public; before eve is installed, read the published Introduction and Getting Started pages. If the project has no Eve app, scaffold one with `pnpm create eve`; to add Eve to an existing app, run `pnpm add eve`. Make sure agent/agent.ts (which sets the model) and agent/instructions.md exist, then add a first typed tool at agent/tools/get_weather.ts using defineTool from eve/tools with a Zod inputSchema and an inline execute. Run it locally with `pnpm dev` (or `eve dev`), then exercise the HTTP API: create a session with POST /eve/v1/session, attach to GET /eve/v1/session/:id/stream, and send a follow-up with the returned continuationToken. Verify with the project's typecheck, adapt model and provider choices to the project, and do not commit unless the user asks.">
+  Set up an Eve agent: read the Eve docs (bundled at node_modules/eve/dist/docs/public once eve is
+  installed), scaffold with `pnpm create eve` (or `pnpm add eve` in an existing app), add a typed
+  tool at agent/tools/get_weather.ts, run it with `pnpm dev`, then create a session, stream it, and
+  send a follow-up.
+</CopyPrompt>
+
+Once `eve` is a dependency, the full docs are bundled in the package, so the agent can read them locally without fetching anything:
+
+- Docs: `node_modules/eve/dist/docs/public/`
+
+To scaffold a project end to end, `pnpm create eve` collects the decisions (name, model, channels), runs setup, adds Slack interactively with `eve channels add slack`, and verifies the result with `eve info --json`.
+
+## What to read next
+
+- [Instructions](./instructions) and [Tools](./tools): the core building blocks
+- [Channels](./channels/overview): reach the agent from Slack, Discord, or a web UI
+- [Frontend](./frontend/overview): browser chat with `useEveAgent`
+- [TypeScript Client](./client/overview): call the agent from scripts or server-side code
+- [Sessions, runs & streaming](./advanced/sessions-runs-and-streaming): the durable session model
+- [Build an agent](./tutorial/first-agent): the full end-to-end walkthrough

package/dist/docs/public/instructions.mdx

@@ -0,0 +1,58 @@
+---
+title: "Instructions"
+description: "Author the agent's always-on system prompt with instructions.md or instructions.ts."
+---
+
+Instructions are the always-on system prompt. Use them for whatever should hold on every turn: a rule, a persona, a constraint. This is the agent's permanent identity, not a procedure it pulls in when the moment calls for it.
+
+Eve prepends the instructions to every model call in the session.
+
+## Author instructions
+
+In the simplest case, instructions are a markdown file at the agent root. Whatever you write is the prompt.
+
+```md title="agent/instructions.md"
+You are a concise assistant. Use tools when they are available.
+```
+
+Keep this file to stable behavior that applies on every turn: identity, tone, standing rules.
+
+## Markdown vs TypeScript
+
+A static prompt belongs in markdown (`agent/instructions.md`). Switch to a TypeScript module (`agent/instructions.ts`) once you need to build the prompt from typed helpers, `lib/` code, or build-time values.
+
+```ts title="agent/instructions.ts"
+import { defineInstructions } from "eve/instructions";
+import { buildInstructionsPrompt } from "./lib/prompts.js";
+
+export default defineInstructions({
+  markdown: buildInstructionsPrompt(),
+});
+```
+
+`defineInstructions` takes one field, `markdown`, which is the resolved prompt text. A module-backed prompt runs once at build time. Eve captures the resulting markdown into the compiled manifest, so the runtime serves the same prompt every session and never re-runs the module.
+
+Got more than one file? An `agent/instructions/` directory works too. Use either `instructions.md` or `instructions.ts` at the agent root, not both.
+
+## How it differs from skills
+
+Instructions and [skills](./skills) both feed text into the model's context. The difference is timing:
+
+|                           | Loaded                                       | Use for                                              |
+| ------------------------- | -------------------------------------------- | ---------------------------------------------------- |
+| `instructions.md` / `.ts` | Always on, every turn                        | Permanent identity and standing rules                |
+| `agent/skills/*`          | On demand, when the model calls `load_skill` | Optional procedures that should not bloat every turn |
+
+Keep instructions short and stable. Long or situational procedures belong in skills, where they only enter context when the request calls for them. See [Skills](./skills).
+
+Instructions never run code. When you need typed executable behavior, reach for a [tool](./tools).
+
+## Dynamic instructions
+
+Need the prompt resolved at runtime from session context (auth, tenant, channel)? Wrap `defineInstructions` in a `defineDynamic` resolver. See [Dynamic capabilities](./advanced/dynamic-capabilities).
+
+## What to read next
+
+- [Tools](./tools): typed actions, the next capability to add
+- [Context control](./advanced/context-control): all the levers for what the model sees
+- [Skills](./skills): on-demand procedures, the counterpart to always-on instructions

package/dist/docs/public/introduction.md

@@ -0,0 +1,102 @@
+---
+title: "Introduction"
+description: "Meet Eve and the small set of ideas behind an Eve agent."
+---
+
+Eve is a framework for building durable agents as ordinary files in a TypeScript project.
+
+Instead of describing your whole agent in one large configuration object, you give each part a clear home: instructions go in one file, tools in one folder, channels in another. Eve discovers that structure and turns it into an agent that runs locally, serves HTTP, connects to other platforms, and keeps working across many turns.
+
+## An Eve project at a glance
+
+A small Eve app looks like this:
+
+```text
+my-agent/
+├── package.json
+└── agent/
+    ├── agent.ts
+    ├── instructions.md
+    ├── tools/
+    │   └── get_weather.ts
+    ├── skills/
+    │   └── plan_a_trip.md
+    └── channels/
+        └── slack.ts
+```
+
+You can understand most Eve projects by reading that tree:
+
+- `instructions.md` tells the agent who it is and how it should behave.
+- [`agent.ts`](./agent-config) chooses the model and configures runtime options.
+- [`tools/`](./tools) holds typed functions the model can call.
+- [`skills/`](./skills) holds longer procedures the model loads only when they are useful.
+- [`channels/`](./channels/overview) connect the agent to HTTP clients, Slack, Discord, and the other places people talk to it.
+
+Start with only `instructions.md` and `agent.ts`. Add the other folders when the agent needs them.
+
+## The files are the interface
+
+Eve is [filesystem-first](./reference/project-layout): a file's location says what it does, and its path usually gives it a name.
+
+For example, this file:
+
+```text
+agent/tools/get_weather.ts
+```
+
+defines a tool named `get_weather`:
+
+```ts
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Get the weather for a city.",
+  inputSchema: z.object({ city: z.string() }),
+  async execute({ city }) {
+    return { city, condition: "Sunny" };
+  },
+});
+```
+
+There is no separate registry to keep in sync. Add the file and Eve discovers it; move or rename it and its identity moves with it. See [Tools](./tools) for the complete API.
+
+## What happens when a message arrives
+
+Whether a message comes from a web app, the terminal, or Slack, the same flow runs. Eve turns the platform input into a message, gives the model its instructions, skills, tools, and conversation history, runs the work (calling tools and subagents as needed), saves the session and streams events, then delivers the result back in the form the platform expects.
+
+That keeps agent behavior portable. Your weather tool does not need to know whether the question came from a browser or from Slack.
+
+## Durable by default
+
+An Eve session is more than one request and one response. It can:
+
+- stream progress while work is happening
+- call tools and subagents
+- pause for [approval or a human answer](./tools)
+- resume after that answer arrives
+- keep durable state across turns
+
+Under the hood, Eve uses the open-source [Workflow SDK](https://workflow-sdk.dev) to make sessions durable, resumable, and crash-safe. Eve handles that machinery so your tools can focus on the work itself.
+
+## Grow the project by adding capabilities
+
+As the agent grows, each concern still has a predictable home:
+
+| Path                            | Add it when you need...                          |
+| ------------------------------- | ------------------------------------------------ |
+| [`connections/`](./connections) | Tools from external MCP servers                  |
+| [`hooks/`](./advanced/hooks)    | Code that reacts to lifecycle and stream events  |
+| [`sandbox/`](./sandbox)         | A controlled workspace for files and commands    |
+| [`subagents/`](./subagents)     | Specialist agents the root agent can delegate to |
+| [`schedules/`](./schedules)     | Recurring or scheduled work                      |
+| `lib/`                          | Shared code imported by the other agent files    |
+
+The result stays readable before it runs: the directory tells you what the agent can do.
+
+## What to read next
+
+- [Getting started](./getting-started): scaffold and run your first agent
+- [Tools](./tools): the typed actions your agent calls
+- [Project layout](./reference/project-layout): every authored slot under `agent/`