eve 0.5.4 → 0.6.0-beta.3

package/dist/docs/public/meta.json

@@ -0,0 +1,22 @@
+{
+  "pages": [
+    "introduction",
+    "getting-started",
+    "---",
+    "agent-config",
+    "instructions",
+    "tools",
+    "skills",
+    "channels",
+    "connections",
+    "sandbox",
+    "subagents",
+    "schedules",
+    "advanced",
+    "frontend",
+    "client",
+    "---",
+    "reference",
+    "tutorial"
+  ]
+}

package/dist/docs/public/reference/cli.md

@@ -0,0 +1,123 @@
+---
+title: "CLI"
+description: "eve command reference: info, build, start, dev, eval."
+---
+
+The `eve` binary (`bin: eve`) runs from your app root, and every command loads `.env`/`.env.local` from that root before it does anything else.
+
+## Commands
+
+| Command                   | Does                                                                                                                                        |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eve info`                | Print the resolved application: discovered tools, skills, subagents, schedules, channels, routes, artifact paths, and discovery diagnostics |
+| `eve build`               | Compile `.eve/` artifacts and build the host output; prints the output directory                                                            |
+| `eve start`               | Serve the built `.output/` app; prints the listening URL                                                                                    |
+| `eve dev`                 | Start the local dev server and open the terminal UI                                                                                         |
+| `eve dev <url>`           | Connect the UI to an existing server URL (e.g. a remote deployment) instead of booting a local server                                       |
+| `eve eval`                | Run eval suites against the local app or a remote target                                                                                    |
+| `eve channels add [kind]` | Scaffold a channel interactively, or by kind (`slack` \| `web`)                                                                             |
+| `eve channels list`       | List user-authored channels                                                                                                                 |
+
+When `eve build` fails on discovery errors, it prints the full diagnostics report (severity, message, source path) and the diagnostics artifact path.
+
+## `eve info`
+
+```bash
+eve info [--json]
+```
+
+| Flag     | Effect       |
+| -------- | ------------ |
+| `--json` | Emit as JSON |
+
+When something behaves unexpectedly, run this first. It confirms a file was discovered, lists the active surface, and surfaces discovery diagnostics, all faster than booting the dev server.
+
+## `eve build`
+
+```bash
+eve build
+```
+
+No flags. Compiles to `.eve/` and builds the host output, then prints the built output path.
+
+Useful artifacts written under `.eve/` (preserved even on partial failure):
+
+| Artifact                                       | Tells you                                            |
+| ---------------------------------------------- | ---------------------------------------------------- |
+| `.eve/discovery/agent-discovery-manifest.json` | What Eve found on disk                               |
+| `.eve/discovery/diagnostics.json`              | Authored-shape errors and warnings                   |
+| `.eve/compile/compiled-agent-manifest.json`    | The serialized authored surface Eve loads at runtime |
+| `.eve/compile/compile-metadata.json`           | Build-time metadata and paths                        |
+| `.eve/compile/module-map.mjs`                  | Compiled module entrypoints Eve imports at runtime   |
+
+## `eve start`
+
+```bash
+eve start [--host <host>] [--port <port>]
+```
+
+| Flag            | Effect                                               |
+| --------------- | ---------------------------------------------------- |
+| `--host <host>` | Host interface to bind                               |
+| `--port <port>` | Port to listen on (defaults to `$PORT`, then `3000`) |
+
+Serves the previously built output. Prints the listening URL.
+
+## `eve dev`
+
+```bash
+eve dev [options]
+eve dev https://your-app.vercel.app
+```
+
+Pass a bare URL as the only argument and the UI connects to that server instead of booting a local one (same as `--url`). That's handy for smoke-testing a preview or production deployment. The interactive UI turns off in a non-TTY terminal.
+
+| Flag                                | Effect                                                                                    |
+| ----------------------------------- | ----------------------------------------------------------------------------------------- |
+| `--host <host>`                     | Host interface to bind                                                                    |
+| `--port <port>`                     | Port to listen on (defaults to `$PORT`, then `3000`)                                      |
+| `-u, --url <url>`                   | Connect to an existing server URL instead of starting one                                 |
+| `--repl`                            | Use the classic line-based REPL instead of the terminal UI                                |
+| `--no-ui`                           | Start the server without an interactive UI                                                |
+| `--name <name>`                     | Title shown in the terminal UI (defaults to the app folder name)                          |
+| `--tools <mode>`                    | Tool-call rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`                |
+| `--reasoning <mode>`                | Reasoning rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`                |
+| `--subagents <mode>`                | Subagent-section rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`         |
+| `--connection-auth <mode>`          | Connection-authorization rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden` |
+| `--assistant-response-stats <mode>` | Assistant header statistic: `tokens` \| `tokensPerSecond`                                 |
+| `--context-size <tokens>`           | Model context window size, shown as a usage percentage                                    |
+| `--logs <mode>`                     | Server/agent logs to show: `all` \| `stderr` \| `none`                                    |
+
+## `eve eval`
+
+```bash
+eve eval [--suite <id...>] [--all] [--url <url>] [options]
+```
+
+| Flag                    | Effect                                         |
+| ----------------------- | ---------------------------------------------- |
+| `--suite <id...>`       | Suite IDs to run (repeatable)                  |
+| `--all`                 | Run all discovered suites                      |
+| `--url <url>`           | Remote agent URL (skip local host startup)     |
+| `--timeout <ms>`        | Per-case timeout in milliseconds               |
+| `--max-concurrency <n>` | Max concurrent case executions per suite       |
+| `--json`                | Output results as JSON                         |
+| `--skip-report`         | Skip suite-defined reporters (e.g. Braintrust) |
+
+See [Evals](../advanced/evals) for authoring suites.
+
+## Recommended loop
+
+1. Edit files under `agent/`.
+2. `eve info` to confirm discovery or read diagnostics.
+3. `eve dev` while iterating locally.
+4. `eve build` before shipping.
+5. `eve start` to smoke-test the built output locally.
+
+Related: [Project layout](./project-layout) · [instrumentation.ts](../advanced/instrumentation).
+
+## What to read next
+
+- [Project layout](./project-layout): what `eve info` discovers
+- [instrumentation.ts](../advanced/instrumentation): tracing and the error catalog
+- [Deployment](../advanced/deployment): `eve build` and `eve start` in production

package/dist/docs/public/reference/faqs.md

@@ -0,0 +1,48 @@
+---
+title: "FAQs"
+description: "Frequently asked questions about Eve."
+---
+
+## How do I view my agent's observability and drill into conversation traces?
+
+When you deploy an Eve agent to Vercel, the platform auto-detects `eve` as the framework, which surfaces an **Agent Runs** tab under your project's **Observability** view in the Vercel dashboard. From there you can browse sessions and drill into each conversation's trace.
+
+> The Agent Runs tab is currently gated: your Vercel team needs the feature enabled before it appears. If you don't see it, reach out to your Vercel contact to get your team enabled.
+
+Agent Runs is separate from the OpenTelemetry exporters configured in [`instrumentation.ts`](../advanced/instrumentation). Those still work and are the recommended path if you want spans in Braintrust, Datadog, or another third-party backend.
+
+## Does Eve use the Chat SDK?
+
+Eve uses Chat SDK's **card-builder components** (Cards, Buttons, Actions, etc.) for composing rich Slack messages. When you build a card with Eve's Slack channel, the underlying primitives come from Chat SDK and get converted to Slack Block Kit at post time.
+
+Eve does **not** use Chat SDK's runtime. The `Chat`, `Adapter`, and `Thread` primitives are never imported or reachable through Eve's public API. Eve's channel layer (webhook handling, signature verification, event parsing, and thread management) is implemented inside Eve itself (see [Channels](../channels/overview)).
+
+In short:
+
+- Building Slack messages: the components feel just like Chat SDK cards.
+- Wiring a channel: you author against Eve's `defineChannel(...)` API, not a Chat SDK adapter.
+
+## How is session data persisted?
+
+Eve persists session state automatically using the [Workflow SDK](https://workflow-sdk.dev), an open-source TypeScript library that makes ordinary functions durable, resumable, and crash-safe. Each Eve session corresponds to one workflow run: when a new message comes in, the runtime either starts a new workflow or resumes an existing one, and the durable context is serialized and threaded forward across each model-call boundary so the session can be reloaded on the next turn.
+
+You don't write workflow code directly. Workflow primitives (`start()`, `resumeHook()`, etc.) are an implementation detail of Eve's runtime layer; channels, tools, and hooks never touch them. This separation is enforced by the framework's mechanical invariants.
+
+If you want session data from your own code, there are two supported surfaces:
+
+- **Tools** can read the current session's metadata (id, turn, auth, parent lineage) via `ctx.session` from the optional `ctx` parameter on `execute`. This is read-only.
+- **`defineState`** is the supported pattern for reading or writing session-scoped durable state from authored code. See [Session context](../advanced/session-context).
+
+For the wire-level session lifecycle (creating sessions, streaming events, reconnecting by event index) see [Sessions, runs & streaming](../advanced/sessions-runs-and-streaming).
+
+## Why didn't Eve discover my file?
+
+Run `eve info`. It lists the discovered surface and prints discovery diagnostics. From there, check that the file sits in the right authored slot and that the root-vs-subagent boundary is valid. See [CLI](./cli) and [Project layout](./project-layout).
+
+## Why can't I call `ctx` at the top of my module?
+
+Runtime helpers on `ctx` (like `ctx.session`) only work inside active authored execution (tools, hooks, lifecycle callbacks), not at module top level. See [Session context](../advanced/session-context).
+
+## Where do auth and network policy live?
+
+On the channel that handles the inbound request. See [Auth & route protection](../advanced/auth-and-route-protection).

package/dist/docs/public/reference/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Reference",
+  "pages": ["typescript-api", "cli", "project-layout", "faqs"]
+}

package/dist/docs/public/reference/project-layout.md

@@ -0,0 +1,111 @@
+---
+title: "Project layout"
+description: "Authored slots under agent/ and the path-derived naming rule."
+---
+
+Eve builds an agent by walking the filesystem under `agent/`. Each directory is an authored slot, and the slot a file lands in determines how Eve loads it.
+
+## Naming rule
+
+Identity comes from the path. You never write a `name` or `id` field on a `define*` call.
+
+| Path                                  | Becomes               |
+| ------------------------------------- | --------------------- |
+| `agent/tools/get_weather.ts`          | tool `get_weather`    |
+| `agent/connections/linear.ts`         | connection `linear`   |
+| `agent/skills/summarize.md`           | skill `summarize`     |
+| `agent/subagents/researcher/agent.ts` | subagent `researcher` |
+
+The root agent takes its name from the enclosing `package.json` `name`. A subagent takes its name from its directory.
+
+## Recommended layout
+
+```text
+my-agent/
+├── package.json
+├── tsconfig.json
+└── agent/
+    ├── agent.ts
+    ├── instructions.md
+    ├── instrumentation.ts
+    ├── channels/
+    ├── connections/
+    ├── hooks/
+    ├── skills/
+    ├── lib/
+    ├── sandbox/
+    ├── tools/
+    ├── schedules/
+    └── subagents/
+```
+
+## Slot table
+
+| Path                                                    | Holds                                       | Notes                                                                                                                                                                                                                       |
+| ------------------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent.ts`                                              | Runtime config                              | Model, modelOptions, compaction, build, experimental. See [Agent config](../agent-config).                                                                                                                                  |
+| `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt                          | A flat file, or a directory of `.md` and `.ts` files. Static sources compose at build time. Dynamic sources (`defineDynamic` + `defineInstructions`) resolve at runtime.                                                    |
+| `instrumentation.ts`                                    | Telemetry config                            | OTel exporter and AI SDK span settings; auto-discovered and run before agent code.                                                                                                                                          |
+| `channels/`                                             | HTTP / messaging entrypoints                | Root-only today.                                                                                                                                                                                                            |
+| `connections/`                                          | External service connections (MCP, OpenAPI) | One connection per file; name derived from filename.                                                                                                                                                                        |
+| `hooks/`                                                | Lifecycle and stream-event subscribers      | Module-backed only. Recursive directories supported.                                                                                                                                                                        |
+| `skills/`                                               | On-demand procedures and capability packs   | Flat markdown, module-backed skills, or packaged skills. Seeded into `/workspace/skills/...`.                                                                                                                               |
+| `lib/`                                                  | Shared authored helper code                 | Import-only; not mounted into the workspace.                                                                                                                                                                                |
+| `sandbox.ts` or `sandbox/sandbox.ts`                    | The agent's single sandbox                  | Use top-level `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` + `sandbox/workspace/**` to also seed files. Framework default applies when neither is authored. Supported on root and local subagents. |
+| `sandbox/workspace/**`                                  | Files seeded into the sandbox               | Mirrored into `/workspace/...` at session bootstrap.                                                                                                                                                                        |
+| `tools/`                                                | Typed executable integrations               | Module-backed only.                                                                                                                                                                                                         |
+| `schedules/`                                            | Recurring jobs                              | Each schedule is `<name>.ts` (default-exported `defineSchedule`) or `<name>.md` (frontmatter `cron:` + prompt body). Recursive nesting supported. Root-only today.                                                          |
+| `subagents/`                                            | Specialist child agents                     | Each child is its own local package under `subagents/<id>/`.                                                                                                                                                                |
+
+## What reaches the runtime workspace
+
+Eve does not mount the whole tree. Only two sources land in the sandbox workspace:
+
+- `skills/` files → `/workspace/skills/...`
+- `agent/sandbox/workspace/**` → `/workspace/...` at session bootstrap
+
+Everything in `lib/` stays import-only source code and never reaches the workspace.
+
+## Local subagent layout
+
+A local subagent lives under `subagents/<id>/` and uses the same `agent.ts` shape as the root.
+
+```text
+agent/subagents/researcher/
+├── agent.ts
+├── instructions.md
+├── hooks/
+├── skills/
+├── lib/
+├── sandbox/
+├── tools/
+└── subagents/
+```
+
+Rules:
+
+- `agent.ts` is required, and must declare a `description`. The parent reads it on the lowered subagent tool to decide when to delegate.
+- `instructions.md` / `instructions.ts` is optional (unlike the root agent, where it is required).
+- `channels/` and `schedules/` are not supported inside local subagents today.
+- Nested subagents are supported.
+
+## Flat layout
+
+Supported when the app root is also the agent root:
+
+```text
+my-agent/
+├── package.json
+├── agent.ts
+├── instructions.md
+├── tools/
+└── skills/
+```
+
+Prefer the nested layout. It keeps the app root separate from the authored surface.
+
+## What to read next
+
+- [`agent.ts`](../agent-config): the runtime config at the root
+- [Tools](../tools): the most common authored slot
+- [TypeScript API](./typescript-api): the define\* helpers and where they import from

package/dist/docs/public/reference/typescript-api.md

@@ -0,0 +1,97 @@
+---
+title: "TypeScript API"
+description: "The define* helpers, the runtime ctx, and where each one is imported from."
+---
+
+This is the public surface of the `eve` package: the `define*` helpers you author with, the `ctx` they receive at runtime, and the import path for each. The full contract lives in `packages/eve/src/public/index.ts`; anything not exported there is a framework internal.
+
+Identity comes from the filesystem, not a field you set. A tool at `agent/tools/get_weather.ts` is `get_weather`, and a connection at `agent/connections/linear.ts` is `linear`, so no definition carries a `name` or `id`.
+
+Most files look the same: import a helper, default-export the result.
+
+```ts title="agent/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({ model: "anthropic/claude-opus-4.8" });
+```
+
+```ts title="agent/tools/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 }, ctx) {
+    return { city, condition: "Sunny" };
+  },
+});
+```
+
+## The define\* helpers
+
+| Helper                                                 | Import from                                   | Authored at                          | Guide                                                    |
+| ------------------------------------------------------ | --------------------------------------------- | ------------------------------------ | -------------------------------------------------------- |
+| `defineAgent`                                          | `eve`                                         | `agent/agent.ts`                     | [agent.ts](../agent-config)                              |
+| `defineTool`                                           | `eve/tools`                                   | `agent/tools/<name>.ts`              | [Tools](../tools)                                        |
+| `defineDynamic`                                        | `eve/tools`, `eve/skills`, `eve/instructions` | `agent/{tools,skills,instructions}/` | [Dynamic capabilities](../advanced/dynamic-capabilities) |
+| `defineMcpClientConnection`, `defineOpenAPIConnection` | `eve/connections`                             | `agent/connections/<name>.ts`        | [Connections](../connections)                            |
+| `defineChannel`                                        | `eve/channels`                                | `agent/channels/<name>.ts`           | [Custom channels](../channels/custom)                    |
+| `eveChannel`, `slackChannel`, and the other platforms  | `eve/channels/<platform>`                     | `agent/channels/<platform>.ts`       | [Channels](../channels/overview)                         |
+| `defineSkill`                                          | `eve/skills`                                  | `agent/skills/<name>.ts`             | [Skills](../skills)                                      |
+| `defineInstructions`                                   | `eve/instructions`                            | `agent/instructions.ts`              | [Instructions](../instructions)                          |
+| `defineHook`                                           | `eve/hooks`                                   | `agent/hooks/<slug>.ts`              | [Hooks](../advanced/hooks)                               |
+| `defineSchedule`                                       | `eve/schedules`                               | `agent/schedules/<name>.ts`          | [Schedules](../schedules)                                |
+| `defineState`                                          | `eve/context`                                 | tools, hooks, lifecycle              | [Session context](../advanced/session-context)           |
+| `defineSandbox`                                        | `eve/sandbox`                                 | `agent/sandbox.ts`                   | [Sandbox](../sandbox)                                    |
+| `defineInstrumentation`                                | `eve/instrumentation`                         | `agent/instrumentation.ts`           | [instrumentation.ts](../advanced/instrumentation)        |
+| `defineRemoteAgent`                                    | `eve`                                         | `agent/subagents/<id>/agent.ts`      | [Remote agents](../advanced/remote-agents)               |
+| `defineEvalSuite`                                      | `eve/evals`                                   | `agent/evals/*.eval.ts`              | [Evals](../advanced/evals)                               |
+| `useEveAgent`                                          | `eve/react`, `eve/vue`, `eve/svelte`          | frontend                             | [Frontend](../frontend/overview)                         |
+
+A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWorkflow` from `eve/tools` (see [Default harness](../advanced/default-harness)), the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval predicates `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`).
+
+## Runtime context (`ctx`)
+
+`ctx` is passed to your tool `execute`, hook handlers, and channel event handlers. It is live only while authored code is actually running, so reaching for it at module top level throws. See [Session context](../advanced/session-context) for the full model.
+
+| Member                     | Use                                                                           |
+| -------------------------- | ----------------------------------------------------------------------------- |
+| `ctx.session`              | Current session, turn, auth, and optional parent lineage (read-only)          |
+| `ctx.getSandbox()`         | Live sandbox handle for the current agent                                     |
+| `ctx.getSkill(identifier)` | Handle for a named skill visible to the current agent                         |
+| `ctx.getToken()`           | Resolve the bearer token for a tool's declared `auth` (throws without `auth`) |
+| `ctx.requireAuth()`        | Force the tool's authorization flow before proceeding                         |
+
+## Imports at a glance
+
+| Import                                                      | Holds                                                                |
+| ----------------------------------------------------------- | -------------------------------------------------------------------- |
+| `eve`                                                       | `defineAgent`, `defineRemoteAgent`                                   |
+| `eve/tools`                                                 | `defineTool`, `defineDynamic`, `disableTool`, `ExperimentalWorkflow` |
+| `eve/tools/defaults`                                        | the built-in tools as plain values                                   |
+| `eve/tools/approval`                                        | `always`, `once`, `never`                                            |
+| `eve/connections`                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`               |
+| `eve/channels`                                              | `defineChannel`, route verbs                                         |
+| `eve/channels/eve`                                          | `eveChannel`                                                         |
+| `eve/channels/auth`                                         | `localDev`, `vercelOidc`, `placeholderAuth`                          |
+| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories                                           |
+| `eve/hooks`                                                 | `defineHook`                                                         |
+| `eve/schedules`                                             | `defineSchedule`                                                     |
+| `eve/skills`                                                | `defineSkill`, `defineDynamic`                                       |
+| `eve/instructions`                                          | `defineInstructions`, `defineDynamic`                                |
+| `eve/context`                                               | `defineState`, session and state types                               |
+| `eve/sandbox`                                               | `defineSandbox`, backends                                            |
+| `eve/instrumentation`                                       | `defineInstrumentation`, `isChannel`                                 |
+| `eve/evals`                                                 | `defineEvalSuite`, loaders, scorers, reporters                       |
+| `eve/react`, `eve/vue`, `eve/svelte`                        | `useEveAgent`                                                        |
+| `eve/next`, `eve/nuxt`, `eve/sveltekit`                     | framework bundler plugins                                            |
+| [`eve/client`](../client/overview)                          | `Client`, `ClientSession`                                            |
+
+Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). For the exhaustive list, read `packages/eve/src/public/index.ts`.
+
+## What to read next
+
+- [`agent.ts`](../agent-config): the agent config these helpers configure
+- [Tools](../tools): `defineTool`, the most-used helper
+- [Project layout](./project-layout): where each define\* lives on disk

package/dist/docs/public/sandbox.mdx

@@ -0,0 +1,198 @@
+---
+title: "Sandbox"
+description: "The agent's isolated bash environment: built-in file tools, a seeded /workspace, backends, lifecycle, and network policy."
+---
+
+The sandbox is the agent's isolated bash environment: a filesystem rooted at `/workspace` where it can run shell commands, execute scripts, and read or write files without ever touching your app runtime. Every Eve agent has exactly one. The built-in `bash`, `read_file`, `write_file`, `glob`, and `grep` tools already target it, and your authored code can too.
+
+You author nothing for the agent to have a working sandbox; it exists by default. Override it only when you need to add setup, seed files, pick a backend, or lock down the network.
+
+## Using the sandbox
+
+The model already has shell and file access through the default tools:
+
+| Tool                       | Does                                |
+| -------------------------- | ----------------------------------- |
+| `bash`                     | run a shell command in the sandbox  |
+| `read_file` / `write_file` | read/write files under `/workspace` |
+| `glob`                     | find files by pattern               |
+| `grep`                     | search file contents                |
+
+All of them run with `/workspace` as the working directory. Any authored runtime function (a tool, a step, a model callback) can grab a live sandbox handle with `ctx.getSandbox()`.
+
+```ts title="agent/tools/run_analysis.ts"
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Run a Python analysis script and return its output.",
+  inputSchema: z.object({ script: z.string() }),
+  async execute({ script }, ctx) {
+    const sandbox = await ctx.getSandbox();
+    await sandbox.writeTextFile({ path: "analysis/run.py", content: script });
+    const result = await sandbox.run({ command: "python analysis/run.py" });
+    return { stdout: result.stdout };
+  },
+});
+```
+
+`ctx.getSandbox()` takes no arguments, is async, and only works inside authored runtime execution.
+
+`/workspace` is one namespace across every backend, so `/workspace/foo` points at the same file whether the backend is local or Vercel. When you need to interpolate a path into a generated command, `sandbox.resolvePath("repo/build.py")` anchors a relative path to its absolute `/workspace/repo/build.py` form. `readFile`, `writeFile`, and `run` do the same anchoring internally.
+
+The handle does more than `run` and `writeTextFile`. In every method, relative paths resolve from `/workspace` and absolute paths pass through untouched:
+
+| Method                                   | Does                                                                                            |
+| ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `run({ command })`                       | run one command, block until it exits, return `{ stdout, stderr, ... }`                         |
+| `spawn(options)`                         | launch a long-running process (server, watcher) and return a `SandboxProcess` handle            |
+| `readTextFile` / `writeTextFile`         | read/write a UTF-8 (or specified encoding) file; `readTextFile` supports 1-based line ranges    |
+| `readBinaryFile` / `writeBinaryFile`     | read/write raw bytes (images, archives, anything non-text)                                      |
+| `readFile` / `writeFile`                 | stream a file in/out as bytes                                                                   |
+| `removePath({ path, force, recursive })` | delete one file or directory; `force` ignores missing paths, `recursive` removes non-empty dirs |
+| `resolvePath(path)`                      | anchor a relative path to its absolute `/workspace/...` form                                    |
+| `setNetworkPolicy(policy)`               | change egress policy mid-turn (Vercel backend only; see [Network policy](#network-policy))      |
+
+Since `run` blocks until the command exits, reach for `spawn` when the process should keep running while the agent does other work:
+
+```ts
+const sandbox = await ctx.getSandbox();
+const server = await sandbox.spawn({ command: "python -m http.server 8000" });
+// ...do other work against the server...
+await server.kill();
+```
+
+A `SandboxProcess` exposes `stdout`/`stderr` byte streams, `wait()` (resolves with the exit code), and `kill()` (idempotent).
+
+`sandbox.id` is a stable per-session identifier that persists across reconnects to the same logical session. Use it as the cache key for per-session state that must outlive individual step executions.
+
+The option types (`SandboxSpawnOptions`, `SandboxReadBinaryFileOptions`, `SandboxWriteBinaryFileOptions`, and so on) are named-exported from `eve/sandbox` alongside `SandboxProcess`.
+
+## Seeding `/workspace`
+
+Mount authored files into the sandbox at session start by placing them under `agent/sandbox/workspace/`. This requires the folder layout (`agent/sandbox/sandbox.ts`), not the top-level shorthand:
+
+```text
+agent/sandbox/
+  sandbox.ts                ← optional override (see below)
+  workspace/
+    schema.sql              ← lands at /workspace/schema.sql
+    scripts/run.sh          ← lands at /workspace/scripts/run.sh
+```
+
+Every file under `workspace/` mirrors into the sandbox cwd with its structure intact, and Eve lists the top-level entries to the model in the prompt automatically. One subtree is off limits: skill discovery already seeds skill files under `/workspace/skills/`, so authoring `agent/sandbox/workspace/skills/...` is rejected. Put those under `agent/skills/` instead.
+
+## Overriding the sandbox
+
+To add setup, seed files, or pick a backend, author `defineSandbox`. There are two layouts:
+
+- `agent/sandbox.ts`: shorthand. Use it when you need only a definition, no seeded files.
+- `agent/sandbox/sandbox.ts`: folder layout. Use it when you also seed `agent/sandbox/workspace/**`. If both exist, the folder layout wins.
+
+```ts title="agent/sandbox/sandbox.ts"
+import { defineSandbox, vercelBackend } from "eve/sandbox";
+
+export default defineSandbox({
+  backend: vercelBackend({ runtime: "node24", resources: { vcpus: 2 } }),
+  revalidationKey: () => "repo-bootstrap-v1",
+  async bootstrap({ use }) {
+    const sandbox = await use();
+    await sandbox.run({ command: "apt-get install -y jq" });
+  },
+  async onSession({ use }) {
+    await use({ networkPolicy: "deny-all" });
+  },
+});
+```
+
+`defineSandbox` lives on `eve/sandbox`. Omit `backend` and the runtime falls back to `defaultBackend()` (see [Backends](#backends)).
+
+## Backends
+
+The backend decides where the sandbox runs. Eve ships three factories from `eve/sandbox`:
+
+| Backend            | Runs the sandbox                                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------------ |
+| `vercelBackend()`  | on [Vercel Sandbox](https://vercel.com/docs/sandbox).                                            |
+| `localBackend()`   | locally via `just-bash`. The default for `eve dev`.                                              |
+| `defaultBackend()` | `vercelBackend()` on hosted Vercel (`process.env.VERCEL` set), `localBackend()` everywhere else. |
+
+With `backend` omitted, Eve uses `defaultBackend()`: `eve dev` on your laptop boots the local backend, and a production build on Vercel uses Vercel Sandbox, no code change in between. `defaultBackend()` also accepts a keyed bag so each inner backend gets its own typed create options:
+
+```ts
+import { defaultBackend, defineSandbox } from "eve/sandbox";
+
+export default defineSandbox({
+  backend: defaultBackend({
+    vercel: { networkPolicy: "deny-all", resources: { vcpus: 4 } },
+    local: {},
+  }),
+});
+```
+
+You can write your own backend too: a `SandboxBackend` is just an object with a `name`, a `create`, and an optional `prewarm`. See the `SandboxBackend*` types on `eve/sandbox`.
+
+## Lifecycle
+
+There are two hooks, scoped differently:
+
+- **`bootstrap({ use })`** is template-scoped and runs once when the template is built. Put reusable setup here, the kind every later session inherits: clone a baseline repo, install dependencies, seed files. Call `use()` to get a `SandboxSession`. Only filesystem state survives snapshotting; config like network policy does not. If external inputs affect what bootstrap produces, set `revalidationKey: () => string` so Eve knows when to rebuild the template (authored sandbox source and seed contents are already tracked for you).
+- **`onSession({ use, ctx })`** is durable-session-scoped and runs once per session. This is where per-session setup goes: network policy, resources, timeout, per-user credentials, one-time markers. Because it runs inside the active runtime context, it can read `ctx.session` and derive the current principal without baking credentials into the template. Call `use(opts?)` to get a `SandboxSession`; `opts` flow to the backend's update path after create.
+
+```ts
+import { defineSandbox, vercelBackend } from "eve/sandbox";
+
+export default defineSandbox({
+  backend: vercelBackend(),
+  async onSession({ use, ctx }) {
+    const sandbox = await use({ networkPolicy: "deny-all" });
+    const user = ctx.session.auth.current;
+    if (user === null) return;
+    await sandbox.writeTextFile({ path: "SESSION_USER.txt", content: `${user.principalId}\n` });
+  },
+});
+```
+
+Sessions are persistent. When the VM shuts down (timeout, default 30 minutes), the filesystem is preserved and the sandbox resumes on the next message as if nothing happened, even days later.
+
+## Network policy
+
+Egress rules go on the backend factory or in `onSession`'s `use()`. There are three forms:
+
+```ts
+networkPolicy: "allow-all"; // default
+networkPolicy: "deny-all";  // block all egress, including DNS
+
+networkPolicy: {
+  allow: ["ai-gateway.vercel.sh", "*.github.com"],
+  subnets: { deny: ["10.0.0.0/8"] },
+};
+```
+
+Set it on the factory (`vercelBackend({ networkPolicy: "deny-all" })`) and it applies from creation, including during `bootstrap`. Set it in `onSession`'s `use()` to override per-session. The common pattern combines both: leave the factory open so `bootstrap` can `git clone`, then lock down in `onSession`. And to change the policy mid-turn, call `sandbox.setNetworkPolicy(...)` on the live handle. That one is Vercel-only; the local backend rejects it.
+
+## Credential brokering
+
+Secrets never enter the sandbox. Instead, the network policy's per-domain `transform` injects credentials at the firewall, so a header can authenticate egress to a host while the secret stays out of the sandbox process entirely:
+
+```ts
+async onSession({ use }) {
+  await use({
+    networkPolicy: {
+      allow: {
+        "github.com": [{ transform: [{ headers: { authorization: "Basic …" } }] }],
+        "*": [],
+      },
+    },
+  });
+}
+```
+
+The `"*": []` catch-all keeps general egress open while the `transform` applies only to `github.com`. For mid-turn brokering, call `setNetworkPolicy` with the same shape. The [Vercel Sandbox docs](https://vercel.com/docs/sandbox) cover the brokering mechanism itself.
+
+## What to read next
+
+- [Subagents](./subagents): each subagent gets its own sandbox, independent of its parent.
+- [Tools](./tools): authored tools run in the app runtime (full `process.env`); only sandbox tools run in the sandbox.
+- [Security model](./advanced/security-model): the app-runtime/sandbox trust boundary in full.
+- [Vercel Sandbox](https://vercel.com/docs/sandbox): platform docs, including credential brokering and persistence limits.