eve 0.5.4 → 0.6.0-beta.3

package/dist/docs/public/advanced/deployment.md

@@ -0,0 +1,113 @@
+---
+title: "Deployment"
+description: "A production checklist for shipping an Eve agent on Vercel: build output, env/secrets, sandbox backend, prewarm, auth, deploy, and verify."
+---
+
+You've got an agent running under `eve dev` and now you want it live. Eve runs the same way locally and on Vercel, so the move to production is mostly mechanical. Work through this checklist in order.
+
+## 1. Build
+
+`eve build` compiles the agent and writes the host output:
+
+```bash
+eve build
+```
+
+On hosted Vercel builds you get the Vercel output bundle under `.vercel/output`. You also get Eve's compiled framework artifacts under `.eve/`: the discovery manifest, compiled manifest, diagnostics, and module map. Crack those open to see exactly which authored surface a deployment will load. For the artifact guide and what to do when `eve build` fails, see [instrumentation.ts](./instrumentation).
+
+## 2. Environment variables & secrets
+
+Set these in your Vercel project's environment variables, never in source or compiled artifacts:
+
+- **A model credential.** Easiest is the Vercel AI Gateway: link a Vercel project and gateway model ids like `anthropic/claude-opus-4.8` authenticate through Vercel OIDC, with no provider keys to manage. To call a provider directly instead, set its key (for example `OPENAI_API_KEY`).
+- **Route-auth secrets**, for example `ROUTE_AUTH_BASIC_PASSWORD` and any JWT/OIDC signing keys referenced by your channel's `auth` (see [Auth & route protection](./auth-and-route-protection)).
+
+Route-auth secrets never get serialized into the compiled discovery or module-map artifacts. The runtime re-materializes them from the authored channel definition instead. One caveat: if your deployment sits behind Vercel preview protection and you want to drive it with `eve dev`, set `VERCEL_AUTOMATION_BYPASS_SECRET` locally before launching.
+
+## 3. Sandbox backend
+
+On Vercel, the [sandbox](../sandbox) runs on hosted [Vercel Sandbox](https://vercel.com/docs/sandbox) infrastructure. Attach the backend on the sandbox definition:
+
+```ts title="agent/sandbox/sandbox.ts"
+import { defineSandbox, vercelBackend } from "eve/sandbox";
+
+export default defineSandbox({
+  backend: vercelBackend(),
+});
+```
+
+Leave `backend` off and Eve falls back to `defaultBackend()`, which picks the Vercel backend on hosted builds and the local backend everywhere else. One definition, both environments.
+
+## 4. Build-time sandbox prewarm
+
+During hosted builds, Eve prewarms reusable Vercel sandbox templates so the first session doesn't eat the cold-start cost. A few things worth knowing:
+
+- Prewarm runs only when both `VERCEL` and `VERCEL_DEPLOYMENT_ID` are present.
+- A sandbox with no `bootstrap()` and no workspace seed files gets skipped.
+- Seed-only templates are keyed by skills and workspace file contents, so unchanged seeds reuse a template across deploys.
+- Templates with a `bootstrap()` are keyed by the optional resolved `revalidationKey()` plus the authored sandbox source and seed contents, so matching inputs reuse a template across deploys.
+- Each template shows up in the build log as either `reused cached` or `built`.
+- Prewarming only covers template construction. `onSession()` still runs at runtime, once per session.
+- **If build-time prewarm fails, the build fails.**
+
+## 5. Auth
+
+Swap any scaffolded `placeholderAuth()` for your real policy before the first production browser request hits the app. Both the framework default and the placeholder reject production browser traffic, so an unconfigured app fails closed rather than serving open routes. See [Auth & route protection](./auth-and-route-protection) for the full walk and the fail-closed guarantee.
+
+## 6. Deploy on Vercel
+
+Deploy with the [Vercel CLI](https://vercel.com/docs/cli) or by pushing to a Git-connected project:
+
+```bash
+vercel deploy
+```
+
+The deployed app serves the same stable health, session, and stream routes you've been hitting locally.
+
+## How Eve sits behind a host framework
+
+You can deploy an Eve app on its own, or mount it inside a host web framework that owns the rest of the site (marketing pages, a dashboard, other API routes). The host keeps its own routing and serves Eve's routes through the framework integration. For mounting Eve in Next.js (`withEve`) and the other supported frameworks, see [Frontend](../frontend/nextjs). Either way, the agent surface and HTTP contract are identical.
+
+## 7. Verify the deployment
+
+Smoke-test the live routes. Health first:
+
+```bash
+curl https://<your-app>/eve/v1/health
+```
+
+Then a real turn:
+
+```bash
+curl -X POST https://<your-app>/eve/v1/session \
+  -H 'content-type: application/json' \
+  -d '{"message":"Hello from production"}'
+```
+
+Attach to the returned stream:
+
+```bash
+curl https://<your-app>/eve/v1/session/<sessionId>/stream
+```
+
+Or poke at the deployment interactively with the dev TUI, which is handy for preview and production smoke tests:
+
+```bash
+eve dev https://<your-app>
+```
+
+(Set `VERCEL_AUTOMATION_BYPASS_SECRET` locally first if the deployment uses preview protection.)
+
+## Checklist
+
+- [ ] `eve build` succeeds and writes `.vercel/output`.
+- [ ] Provider keys and route-auth secrets are set in Vercel env vars.
+- [ ] The sandbox backend matches the environment (`vercelBackend()` or `defaultBackend()`).
+- [ ] Build-time prewarm reused or built templates without failing.
+- [ ] `placeholderAuth()` is replaced with your real policy.
+
+## What to read next
+
+- [Auth & route protection](./auth-and-route-protection): secure the routes you deployed
+- [instrumentation.ts](./instrumentation): tracing, run tags, and the error catalog
+- [Sandbox](../sandbox): backends, lifecycle, and credential brokering

package/dist/docs/public/advanced/dev-tui.md

@@ -0,0 +1,37 @@
+---
+title: "Dev TUI"
+description: "Drive an Eve agent locally in an interactive terminal UI: chat, stream, approve tools, answer questions, tune the display, and point it at a deployment."
+---
+
+`eve dev` boots the local runtime and drops you into an interactive terminal UI. You chat with the agent, watch it stream, approve its tool calls, and answer the questions it asks back:
+
+```bash
+eve dev
+```
+
+The screen has three parts. A header shows the app name and live response stats. The middle is a scrollable transcript of everything that happened: your prompts, streamed messages, reasoning, tool calls, subagent sections, connection-authorization prompts, and any captured `stdout`/`stderr`. The bottom is an input and status bar. Press `Enter` to send and `↑`/`↓` to scroll. `q` quits when the agent is idle, and `Ctrl+C` quits at any time. Two slash commands: `/new` starts a fresh session and `/exit` quits.
+
+The agent will sometimes need something from you, and the TUI asks inline. Tool approvals are a `y`/`n`. Option questions let you pick with `↑`/`↓` and `Enter`, or you can type a freeform answer. If a tool needs an authorized [connection](../connections), the URL shows up right in the transcript, and the turn picks back up once you've finished the flow.
+
+Density flags accept `full` / `collapsed` / `auto-collapsed` / `hidden`:
+
+```bash
+eve dev --tools full --assistant-response-stats tokens --context-size 200000
+```
+
+Other useful flags: `--subagents`, `--reasoning`, `--logs <all|stderr|none>`, `--host`/`--port`, and `--no-ui` (headless, also the automatic fallback when stdout isn't a TTY).
+
+## Remote: `eve dev <url>`
+
+Pass a URL and the TUI talks to a running deployment instead of spinning up a local server. That's handy for a Vercel preview or your production app:
+
+```bash
+eve dev https://<your-app>
+```
+
+The bare URL is shorthand for `--url`. `--host`, `--port`, and `--no-ui` are ignored against a remote target. If the deployment sits behind Vercel preview protection, set `VERCEL_AUTOMATION_BYPASS_SECRET` locally first. See [Deployment](./deployment) for the smoke-test flow.
+
+## What to read next
+
+- [instrumentation.ts](./instrumentation): OpenTelemetry, hooks, and the error catalog.
+- [CLI](../reference/cli): every command and flag.

package/dist/docs/public/advanced/dynamic-capabilities.md

@@ -0,0 +1,129 @@
+---
+title: "Dynamic Capabilities"
+description: "Resolve tools, skills, and instructions at runtime with defineDynamic: the resolver events, execution order, and how dynamic tools survive step boundaries."
+---
+
+Sometimes you can't name a tool until the session starts. `defineDynamic` resolves capabilities from a session event at runtime rather than declaring them up front, which is what you want when the right tools, skills, or instructions hinge on who the caller is, what tenant they belong to, feature flags, or external data. The [tools](../tools), [skills](../skills), and [instructions](../instructions) guides each point here for their dynamic form.
+
+## Dynamic tools
+
+Pass `defineDynamic` an `events` object whose handlers return either a single `defineTool(...)`, a `Record<string, defineTool(...)>`, or `null` for no tools. Wrap every entry in `defineTool()`. The wrapper stamps them so their `execute` functions survive workflow step boundaries.
+
+The example below builds one tool per warehouse table. A map return names tools `slug__key`, so the model sees `query__orders`, `query__users`, and so on:
+
+```ts title="agent/tools/query.ts"
+import { defineDynamic, defineTool } from "eve/tools";
+import { z } from "zod";
+import { listTables, runReadOnly } from "../lib/warehouse.js";
+
+export default defineDynamic({
+  events: {
+    "session.started": async (_event, ctx) =>
+      Object.fromEntries(
+        (await listTables()).map((t) => [
+          t.name,
+          defineTool({
+            description: `Query ${t.name}. Columns: ${t.columns.join(", ")}`,
+            inputSchema: z.object({ sql: z.string() }),
+            execute: ({ sql }) => runReadOnly(t.name, sql),
+          }),
+        ]),
+      ),
+  },
+});
+```
+
+### Naming
+
+| Return shape              | File                       | Tool name(s)                      |
+| ------------------------- | -------------------------- | --------------------------------- |
+| single `defineTool`       | `agent/tools/analytics.ts` | `analytics`                       |
+| map `{ export, query }`   | `agent/tools/tenant.ts`    | `tenant__export`, `tenant__query` |
+| map `{ run }` (one entry) | `agent/tools/search.ts`    | `search__run`                     |
+
+A single return produces one tool named after the file slug, identical to a static tool. A map always uses `slug__key`, even when it holds a single entry, so adding a second entry later never renames the first.
+
+### Events
+
+| Event             | Resolver runs          | Tools available for             |
+| ----------------- | ---------------------- | ------------------------------- |
+| `session.started` | Once per session       | Every model call in the session |
+| `turn.started`    | Once per turn          | Every model call in the turn    |
+| `step.started`    | Before each model call | That model call                 |
+
+**Limitation.** `execute` must be an inline function (function expression, arrow, or method shorthand written directly as the property value). `execute: myFn` or `execute: makeFn()` is not detected by the transform, so the tool works on the first step but won't survive replay.
+
+### Execution order
+
+When a stream event fires, three things happen in order: the channel adapter handler runs and the event is written to the durable stream, then stream-event [hooks](./hooks) fire, then dynamic tool resolvers subscribed to that event run and update the tool set. The tool loop reads the current set right before each model call, so a mid-turn update is visible on the next call.
+
+A single file can declare handlers for several events, and the most recently fired one owns that file's tool set. Re-resolve on `turn.started` to replace what `session.started` returned:
+
+```ts title="agent/tools/catalog.ts"
+export default defineDynamic({
+  events: {
+    "session.started": async (_event, ctx) => ({
+      query: defineTool({
+        /* ... */
+      }),
+    }),
+    // On each turn, re-resolve. Replaces this file's session.started tools for later calls.
+    "turn.started": async (_event, ctx) => ({
+      search: defineTool({
+        /* ... */
+      }),
+    }),
+  },
+});
+```
+
+Resolvers across files run concurrently. On later steps the bundler transform reconstructs each `execute` from its stored closure variables instead of re-running the resolver, which is why `execute` has to be inline.
+
+## Dynamic skills
+
+A dynamic skills file resolves which [skill](../skills) a caller can load, keyed on the principal. It resolves on `session.started` and `turn.started` only (`step.started` is reserved for dynamic tools). Read `ctx.session.auth` or channel metadata and return a `defineSkill(...)` (named after the file slug) or `null`:
+
+```ts title="agent/skills/team_playbook.ts"
+import { defineDynamic, defineSkill } from "eve/skills";
+import { PLAYBOOKS } from "../lib/playbooks.js";
+
+export default defineDynamic({
+  events: {
+    "session.started": (_event, ctx) => {
+      const team = ctx.session.auth.current?.attributes.team;
+      const markdown = team ? PLAYBOOKS[team] : undefined;
+      return markdown ? defineSkill({ markdown }) : null;
+    },
+  },
+});
+```
+
+The caller's team gets its own playbook advertised as a loadable skill; everyone else gets nothing.
+
+## Dynamic instructions
+
+A dynamic instructions file resolves the per-session system prompt the same way, returning `defineInstructions(...)` built from the principal, tenant, or external data:
+
+```ts title="agent/instructions/persona.ts"
+import { defineDynamic, defineInstructions } from "eve/instructions";
+
+export default defineDynamic({
+  events: {
+    "session.started": (_event, ctx) => {
+      const plan = ctx.session.auth.current?.attributes.plan ?? "free";
+      return defineInstructions({
+        markdown: `The caller is on the ${plan} plan. Match the depth of your answers to it.`,
+      });
+    },
+  },
+});
+```
+
+Both resolve before the prompt is assembled, so the model sees the right instructions and skill set for whoever is calling, without that context reaching anyone else.
+
+## What to read next
+
+- The static tool basics this builds on → [Tools](../tools)
+- The built-in tools and how to override them → [Default harness](./default-harness)
+- Authenticate a tool or connection to an external service → [Auth & route protection](./auth-and-route-protection)
+- Durable per-session memory for resolvers to read → [State](./state)

package/dist/docs/public/advanced/dynamic-workflows.md

@@ -0,0 +1,55 @@
+---
+title: "Dynamic Workflows"
+description: "The experimental Workflow tool: let the model orchestrate its own subagents from model-authored JavaScript as one durable step."
+---
+
+The experimental `Workflow` tool lets the model write JavaScript that coordinates the agent's own subagents as a single durable step: running them in sequence, feeding one result into the next, fanning out over a list, and combining the results. You flip on the capability; the model decides and runs the orchestration. Think of it as the agents-only slice of code mode.
+
+A single turn can already call several subagents, and parallel tool calls dispatch concurrently. What a workflow adds is _programmatic_ coordination: how many subagents to run based on an earlier result, which output feeds which call, and how to combine everything. That's logic the model can't express as a few one-off calls.
+
+## Enable it
+
+Re-export the opt-in marker as the default export of `agent/tools/workflow.ts`. The marker name carries the "experimental" warning, but the tool the model actually sees is named `Workflow`.
+
+```ts title="agent/tools/workflow.ts"
+export { ExperimentalWorkflow as default } from "eve/tools";
+```
+
+Without that file, the `Workflow` tool stays off. It earns its keep only when the agent has subagents (or the built-in `agent`) worth coordinating:
+
+```ts title="agent/subagents/analyst/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  description: "Analyzes one metric: queries, computes, writes a short finding.",
+  model: "anthropic/claude-opus-4.8",
+});
+```
+
+Ask for a "weekly business review": the model map-reduces `analyst` over the metrics it picks (width decided at runtime) and resumes if a child parks for approval.
+
+## What it can orchestrate
+
+A workflow reaches only this agent's own agents: the built-in `agent` (a copy of itself), declared [subagents](../subagents), and [remote agents](./remote-agents). That's the whole list. No files, network, shell, skills, or connections. It's a coordination layer over subagents, not a place to do other work. Each call can still request structured output via `outputSchema`, exactly like a direct subagent delegation.
+
+## Where the JavaScript runs
+
+The orchestration code never touches the agent's process. The runtime hands the program text to a small isolated JavaScript engine (a QuickJS sandbox) and runs it there. Nothing from the host realm crosses in: no `process`, no `globalThis` from the agent, no `import`/`require`. The program can reach exactly two things, the agent functions bridged in as `tools.<name>` and the ordinary language built-ins.
+
+That's an allowlist, not a denylist. The sandbox can't read files, open a socket, or see an environment variable because those simply aren't present, not because each one is blocked in turn. When the program calls an agent function, that call bridges back out to the runtime, which dispatches it just like a direct delegation. The orchestration glue stays inside the sandbox.
+
+## How it behaves
+
+- **Durable.** The whole orchestration counts as one step. Subagents dispatched together run concurrently, and if a run parks on a long-running or human-gated child, it resumes where it left off after a restart.
+- **HITL-safe.** A subagent that needs approval mid-run surfaces its request to the user, and the workflow picks back up once that's answered, same as direct delegation.
+- **Observable.** Every orchestrated subagent emits the usual `subagent.called` / `subagent.completed` events on the parent stream and gets its own child session and stream. The telemetry matches direct delegation, so existing dashboards and cost attribution keep working.
+
+## Relationship to code mode
+
+Code mode is the broader version: the model drives _all_ of an agent's tools (files, shell, web, and agents) from JavaScript. A workflow carves out the agents-only slice, just the subagents. The two don't interfere. Enabling the `Workflow` tool leaves code mode untouched, and an agent can run both at once.
+
+## What to read next
+
+- Declare the subagents a workflow orchestrates → [Subagents](../subagents)
+- Call another deployment as one of those agents → [Remote agents](./remote-agents)
+- The `agent/tools/` opt-in mechanism → [Default harness](./default-harness)

package/dist/docs/public/advanced/evals.md

@@ -0,0 +1,121 @@
+---
+title: "Evals"
+description: "Define repeatable scored checks for an Eve agent with defineEvalSuite and run them with eve eval."
+---
+
+An eval is a scored check that runs your agent against real sessions and grades the result. Use it to catch regressions when you change a prompt or a tool: compare the output against expected text, JSON, SQL, or behavior, and optionally ship the results to Braintrust.
+
+## `defineEvalSuite`
+
+Eve discovers suites under the app-root `evals/` directory, in `.eval.ts` files. The file path is the suite's identity, so you don't author an `id` or `name`.
+
+```text
+my-agent/
+├── agent/
+├── evals/
+│   ├── smoke.eval.ts
+│   └── weather.eval.ts
+└── package.json
+```
+
+```ts title="evals/weather.eval.ts"
+import { defineEvalSuite } from "eve/evals";
+import { Run } from "eve/evals/scores";
+
+export default defineEvalSuite({
+  model: "anthropic/claude-opus-4.8",
+  description: "Basic message and tool-usage coverage for the weather agent.",
+  cases: [
+    { id: "brooklyn-forecast", input: "What is the weather in Brooklyn?", expected: "Sunny" },
+  ],
+  scores: [Run.didNotFail()],
+});
+```
+
+Every suite needs `model`, `scores`, and either `cases` or `load`. The rest are optional: `description`, `task`, `thresholds`, `modelOptions`, `tags`, `metadata`, `maxConcurrency`, `timeoutMs`, `reporters`. The init template adds `evals/**/*.ts` to `tsconfig.json`, so your eval code type-checks alongside the app.
+
+One thing that trips people up: `model` is the scorer model, not the agent's. Eve only uses it for model-backed scoring, never to swap out the agent under test. Pass a string id (e.g. `"anthropic/claude-opus-4.8"`) to route through the Vercel AI Gateway, or hand it an AI SDK model instance to use that directly.
+
+## Cases and tasks
+
+A case pairs an `input` with an `expected`, plus optional tags and metadata. `input` can be a string or an object. `expected` is optional, which is handy when you only care about behavior. List cases inline, or load them dynamically:
+
+```ts
+import { defineEvalSuite } from "eve/evals";
+import { loadYaml } from "eve/evals/loaders";
+import { Text } from "eve/evals/scores";
+
+export default defineEvalSuite({
+  model: "anthropic/claude-opus-4.8",
+  async load() {
+    const doc = await loadYaml("evals/data/cases.yaml");
+    return (doc.evals as readonly { task: string; prompt: string; sql: string }[]).map((row) => ({
+      id: row.task,
+      input: row.prompt,
+      expected: row.sql,
+    }));
+  },
+  scores: [Text.exact()],
+});
+```
+
+The loaders (`loadJson`, `loadYaml` from `eve/evals/loaders`) resolve paths relative to the app root. They're meant for fixtures, not runtime agent code. For the task itself, `task.prompt` covers the single-string case, `task.messages` sets up a multi-turn conversation, and `task.parseOutput` lets you compare a transformed result rather than the raw final message.
+
+## Scorers and rubrics
+
+Scorers live in namespaces on `eve/evals/scores`. Pick the cheapest one that captures what "correct" means here. The deterministic scorers run instantly for free; an LLM judge runs once per case and burns tokens, so save it for when nothing simpler will do.
+
+| Need                                                        | Use                                                                                    |
+| ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Assert agent behavior (run succeeded, used the right tools) | `Run.didNotFail()`, `Run.usedTool(name)`, `Run.usedNoTools()`, `Run.maxToolCalls(max)` |
+| Exact string match                                          | `Text.exact()`, `Text.includes()`                                                      |
+| Fuzzy text match (typos, whitespace)                        | `Text.levenshtein()`                                                                   |
+| Exact JSON match                                            | `Json.deepEqual()`                                                                     |
+| Exact SQL match (after normalization)                       | `Sql.exactNormalized()`                                                                |
+| LLM-judged factual correctness vs an expected answer        | `Autoevals.factuality()`                                                               |
+| LLM-judged summary quality                                  | `Autoevals.summary()`                                                                  |
+| LLM-judged SQL semantic equivalence                         | `Autoevals.sql()`                                                                      |
+| LLM-judged free-form criteria (no `expected` to match)      | `Autoevals.closedQA({ criteria: "..." })`                                              |
+
+Each scorer gets the flattened `input`, `output`, and `expected` strings along with the full case and task result. Return `null` from a scorer to skip a case.
+
+### Thresholds
+
+By default a scorer has to hit an exact match to pass. `thresholds` loosens that, mapping each scorer name to the minimum score you'll accept:
+
+```ts
+defineEvalSuite({
+  model: "anthropic/claude-opus-4.8",
+  cases: [{ id: "hello", input: "Hello", expected: "Hello" }],
+  scores: [Run.didNotFail(), Text.includes()],
+  thresholds: { "run.didNotFail": 1, "text.includes": 0.5 },
+});
+```
+
+`maxConcurrency` caps parallelism and `timeoutMs` bounds each case. Leave them off and `eve eval` runs up to 8 cases per suite at once. For provider-specific scorer-model settings, use `modelOptions.providerOptions`. Individual Autoevals scorers can also take their own `model` / `modelOptions`, which win over the suite default.
+
+## Reporters
+
+Suite-level reporters live on `eve/evals/reporters`. Right now the public surface is `Braintrust(...)`, which uploads suite results to Braintrust experiments. Eve still runs and scores everything itself; the reporter just ships the results out. Suite and case `metadata` ride along to the reporter, and the CLI prints a console summary by default.
+
+## Running evals
+
+```bash
+eve eval                       # run discovered suites locally
+eve eval --all                 # run all discovered suites
+eve eval --suite weather       # run selected suites
+eve eval --url https://<app>   # target a remote app instead of a local host
+eve eval --json                # machine-readable output
+eve eval --skip-report         # skip suite-defined reporters (e.g. Braintrust)
+```
+
+Each run drops per-suite artifacts under `.eve/evals/<timestamp>-<suite-id>/`.
+
+## A good baseline
+
+Most apps do fine with a small smoke suite. Score behavior with `Run.didNotFail()` and one or two content assertions, keep case fixtures in `evals/data/`, and only reach for Braintrust once you actually need shared result review or experiment history.
+
+## What to read next
+
+- [Tools](../tools): the surface most evals assert on
+- [instrumentation.ts](./instrumentation): tracing and debugging

package/dist/docs/public/advanced/execution-model-and-durability.md

@@ -0,0 +1,48 @@
+---
+title: "Execution Model & Durability"
+description: "How a session runs: durable conversations, turns that checkpoint at steps, and parked work that resumes later."
+---
+
+A session is a durable conversation. It can run for days, and it survives process restarts and redeploys without any work on your part. You write the capabilities (tools, instructions, channels) and Eve runs the loop.
+
+## Sessions, turns, and steps
+
+Work nests in three levels:
+
+- **session**: the whole durable conversation or task. It's long-lived and can span many requests over days or weeks without losing context.
+- **turn**: one user message and all the work it triggers (model calls, tool calls, reasoning) until the agent produces its response.
+- **step**: a durable checkpoint inside a turn (one model call and the tool calls it makes).
+
+Every turn runs as a durable workflow, built on the open-source [Workflow SDK](https://workflow-sdk.dev/) (Vercel Workflow when you deploy on Vercel). Eve checkpoints progress at each step and serializes durable state at that boundary. Your code runs inside a managed step, so tools, the sandbox, and subagents feel synchronous even though the session underneath them is durable.
+
+## Resuming after a crash
+
+Crash the process, hit a timeout, or redeploy mid-turn, and the run picks up from the last completed step rather than replaying the whole turn. Re-running a step from the same input is idempotent. Your tool calls don't fire twice, so a resume never doubles up a side effect (a charge, an email, a write).
+
+There's nothing to configure here. Eve owns the workflow lifecycle, and sessions are durable by default.
+
+## Parked work
+
+Some work has to wait: a human approving a [tool](../tools), an interactive OAuth sign-in for a [connection](../connections), or a long-running [subagent](../subagents). At those points the turn parks durably. The workflow suspends and holds no compute until the input it's waiting on shows up (a click, a callback, a child completing), even if that's much later. When it does, the conversation picks up exactly where it left off.
+
+## Message delivery and queueing
+
+Eve does not maintain a durable FIFO queue of user messages for a session today. The `continuationToken` is a resume handle for the session's current workflow hook, not a general message-queue address.
+
+When a session is waiting, a delivery to the current continuation token wakes the session and starts the next turn. When a turn is already active, additional deliveries may be accepted by the hook, but the runtime only drains them at specific workflow boundaries. If more than one delivery is already ready when the driver checks, Eve may fold them into the next turn; that drain is best-effort and depends on workflow and transport timing.
+
+That means applications should not rely on concurrent sends to the same session behaving like a typical ordered chat queue. For deterministic behavior, send one user turn at a time: wait for `session.waiting` before sending the next message to the same session. If your channel can receive bursts while the agent is working, keep your own per-session queue in the channel or app layer, then deliver the next message after the session parks again. Separate sessions can still run independently.
+
+## Subagents
+
+A turn can hand work off to a [subagent](../subagents). Each subagent gets its own context and its own durable session; a declared subagent also gets its own sandbox, skills, and state. Nothing crosses the boundary implicitly.
+
+## Ordering
+
+Conversation history within a session is append-only. Turns land in order, and the tool calls inside a turn (plus their results) keep their order too. Read a session back and you see things in the order they happened.
+
+## What to read next
+
+- [Sessions, runs & streaming](./sessions-runs-and-streaming): the handles you hold and the event stream you watch.
+- [Security model](./security-model): the trust boundaries the runtime enforces.
+- [State](../advanced/state): durable per-session memory that persists across step boundaries.

package/dist/docs/public/advanced/hooks.md

@@ -0,0 +1,154 @@
+---
+title: "Hooks"
+description: "Subscribe to runtime stream events from agent/hooks/."
+---
+
+Hooks are Eve's authored extension points for the runtime event stream. A hook subscribes to stream events and runs side effects after each event is durably recorded: audit logging, metrics and alerting, or persisting every session and message to your own database for analytics. Reach for one when you want to observe what the agent does without writing a tool, a context provider, or a channel adapter handler.
+
+## Define a hook
+
+```ts title="agent/hooks/audit.ts"
+import { defineHook } from "eve/hooks";
+
+export default defineHook({
+  events: {
+    async "session.started"(_event, ctx) {
+      console.info("session started", { sessionId: ctx.session.id });
+    },
+    async "message.completed"(event) {
+      console.info("model finished", { length: event.data.message?.length ?? 0 });
+    },
+  },
+});
+```
+
+The slug is the path-relative basename: `agent/hooks/audit.ts` becomes `"audit"`, and `agent/hooks/auth/load-profile.ts` becomes `"auth/load-profile"`.
+
+`defineHook`, `HookDefinition`, and `HookContext` live on `eve/hooks`. The `defineState` helper lives on `eve/context`.
+
+## Shape
+
+A hook file declares stream-event subscribers under the `events` map:
+
+```ts
+defineHook({
+  events: {
+    "session.started"(event, ctx) {
+      /* ... */
+    },
+    "turn.completed"(event, ctx) {
+      /* ... */
+    },
+    "*"(event, ctx) {
+      /* wildcard: fires for every event */
+    },
+  },
+});
+```
+
+Handlers are observe-only: they cannot inject model context. To contribute runtime model messages, use `defineDynamic` + `defineInstructions` in `agent/instructions/`.
+
+Every handler receives the same `HookContext`:
+
+```ts
+interface HookContext {
+  readonly agent: { readonly name: string; readonly nodeId?: string };
+  readonly channel: { readonly kind?: string; readonly continuationToken?: string };
+  readonly session: { readonly id: string };
+}
+```
+
+### Narrowing tool results
+
+`toolResultFrom` narrows an `action.result` event to a specific authored tool or MCP connection and returns typed output. Import it from `eve/tools`:
+
+```ts
+import { defineHook } from "eve/hooks";
+import { toolResultFrom } from "eve/tools";
+import getWeather from "../tools/get-weather";
+import linear from "../connections/linear";
+
+export default defineHook({
+  events: {
+    "action.result"(event) {
+      // Authored tool: output is typed as the tool's return type
+      const weather = toolResultFrom(event.data.result, getWeather);
+      if (weather) {
+        console.log(weather.output.temperature);
+      }
+
+      // MCP connection: output is unknown, toolName is qualified
+      const linearResult = toolResultFrom(event.data.result, linear);
+      if (linearResult) {
+        console.log(linearResult.connectionToolName, linearResult.output);
+      }
+    },
+  },
+});
+```
+
+Returns `undefined` when the result doesn't match, or when `isError` is `true`. For authored tools the return includes `{ output, toolName, callId }` with `output` typed as the tool's `TOutput`. For connections it includes `{ output, toolName, connectionToolName, callId }` with `output` as `unknown`.
+
+## Stream events
+
+Side-effect-only handlers for accepted runtime events. Subscribe by event type, or use `*` for every event:
+
+```ts title="agent/hooks/observability.ts"
+import { defineHook } from "eve/hooks";
+import { datadogCounter } from "../lib/datadog";
+import { postToHoneycomb } from "../lib/honeycomb";
+
+export default defineHook({
+  events: {
+    async "session.started"(_event, ctx) {
+      await postToHoneycomb({ event: "session.started", sessionId: ctx.session.id });
+    },
+    async "message.completed"(event) {
+      await postToHoneycomb({ event: "message.completed", payload: event.data });
+    },
+    async "*"(event) {
+      datadogCounter(`eve.event.${event.type}`).increment();
+    },
+  },
+});
+```
+
+### Execution order
+
+When a stream event fires, three things happen in order:
+
+1. Emit: the channel adapter handler runs, then the event is written to the durable stream.
+2. Hooks: stream-event hooks fire (typed handlers first, then the `*` wildcard). Return values are ignored.
+3. Dynamic tool resolvers: resolvers subscribed to the event type run and update the tool set.
+
+Hooks always run after the event is durably recorded, so if a hook throws, the stream stays consistent.
+
+## Errors
+
+| Stage      | On throw                                                                                                                                                           |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `events.*` | Propagates through the emit composer and surfaces as `turn.failed`. If a hook subscribed to a failure-cascade event also throws, it escalates to `session.failed`. |
+
+For belt-and-suspenders semantics inside a hook, wrap the body in `try`/`catch`. Eve treats a thrown hook as a real failure.
+
+## Subagent isolation
+
+Subagents may carry their own `agent/hooks/` directory. Subagent hooks fire only inside the subagent scope: parent-agent hooks do not fire for subagent turns, and subagent hooks see only the subagent's own context.
+
+## Hook vs tool vs provider
+
+| Need                                              | Use                                            |
+| ------------------------------------------------- | ---------------------------------------------- |
+| Observe runtime events (audit, metrics, alerting) | `events.<type>` (or a channel adapter handler) |
+| Provide structured input to the model on demand   | a tool                                         |
+| Make a value available across the entire step     | a context provider                             |
+| Subscribe to platform-specific events             | a channel adapter handler                      |
+
+Stream-event hooks and channel adapter event handlers are structurally identical. Choose the channel adapter handler when you are authoring adapter-specific behavior, and choose `events.*` when you are authoring agent-level behavior that should fire across every channel. Both fire when both are registered.
+
+## What to read next
+
+- [Tools](../tools)
+- [Context control](./context-control)
+- [Session context](./session-context)
+- [Sessions, runs & streaming](./sessions-runs-and-streaming)