eve 0.10.0 → 0.11.1

package/docs/guides/dev-tui.md

@@ -1,44 +1,116 @@
 ---
 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."
+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:
+`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
 ```
 
-On startup the TUI prints a brand line with your agent's name, plus a rotating tip (local sessions only):
+On startup the TUI prints a brand line with your agent's name, plus a rotating tip (local sessions only).
 
 ```text
  eve weather-agent
  Use /channels to add more ways to reach your agent.
 ```
 
-If agent discovery reported problems, an error/warning count renders between the two lines. Instructions, tools, skills, and subagents are one `eve info` away, and `/help` lists every command.
+If agent discovery reported problems, an error and warning count renders between the two lines. Instructions, tools, skills, and subagents are one `eve info` away, and `/help` lists every command. The TUI also runs a startup check. A missing model-provider setup surfaces as an attention line (`⚠ 1 setup issue: model provider not linked · /model`) so the fix is visible before the first message fails, with each command's outcome hanging under it on a `⎿` connector.
 
-From there the conversation streams straight into your terminal's normal scrollback — your prompts, the agent's replies, reasoning, tool calls, nested subagents, connection-authorization prompts, and any captured `stdout`, `stderr`, or sandbox lifecycle lines — so you keep native scrolling, copy/paste, and a transcript that persists after you exit. Each turn is rendered without boxes: a colored gutter glyph marks who's speaking, tool calls collapse to a one-line summary (`✓ get_weather  city="SF" → 73°F`), and a subagent's work is indented beneath its `◆` header. A sticky footer keeps you oriented. When input is ready, the prompt stays bare until you type; while a turn or setup action owns the terminal, only its live status is shown. Beneath the prompt or status, a persistent line shows the model, the session's token flow (`↑ 394.4K ↓ 4.3K`), the linked Vercel project and team (`▲ my-agent (acme)`), and a yellow `/deploy pending` marker once a channel added this session still needs `/deploy`. The Vercel segment stays hidden until the directory is linked. Press `Enter` to send; `Ctrl+C` interrupts a running turn or quits at the prompt. Slash commands: `/new` starts a fresh session and `/exit` quits.
+## Reading the transcript
 
-When `eve dev` runs the server locally, five more slash commands manage the project without leaving the session. `/vc` installs the Vercel CLI (a global install with your package manager) when it is missing — the fix command the "Vercel CLI not found" diagnostic points at. `/login` signs in to Vercel through the CLI's browser flow: the panel waits while you authenticate in the browser and Cancel stops waiting. These are the prerequisites the others route to — a logged-out `/model` link, `/channels` Slack provisioning, and `/deploy` all point you at `/login` (or `/vc` when the CLI itself is absent) instead of failing with a raw error, and a `403` from a team that enforces SSO routes to `/login` too (re-authenticating completes the team's SSO). Bare `/model` opens a configure menu that loops until Done (or Esc). "Change model" runs the same searchable model picker setup uses (the AI Gateway catalog, pre-selected on the model the runtime is serving); a model change is written into your agent's authored source, and the command reports success only after Eve confirms the new id (`/model <provider/model-id>` applies one directly, skipping the menu). The provider row opens the provider questions: which model provider to use (picking something other than AI Gateway shows wiring instructions for your own provider and stops there, leaving any existing setup untouched) and how to connect to AI Gateway — paste your own `AI_GATEWAY_API_KEY`, saved straight to `.env.local`, or connect via a project, which asks for a Vercel team and then opens that team's existing-project list (picking again re-links) before pulling the project's environment so an AI Gateway credential lands in `.env.local`; the dev server reloads env files automatically, no restart needed. The row demands attention (a bold yellow "Configure provider" with "Required to enable the agent") until a link or gateway credential is detected, then names the connection (e.g. "AI Gateway (Linked to my-project in my-team)") after, and each action's latest outcome stays visible beneath the menu (e.g. "✓ Model changed to openai/gpt-5.5"). `/channels` shows the agent's channel list — already-registered channels render as checked, focusable rows with an "Already installed" hint — and adds the one you pick, including the Slack Connect provisioning, then installs the dependencies the scaffold added so the dev server can load the new channels right away; after each addition the list repaints with the channel checked, until Done (or Esc) leaves the flow. `/deploy` ships the agent to Vercel production, linking first when the directory is unlinked. Each command echoes as an invocation line, asks through a bordered panel that takes the input area's place — one question at a time, clearly separate from the chat transcript — and finishes with a one-line `⎿` result; loading states stay on the ephemeral status line instead of piling into the transcript. These commands are not available when connected to a remote server with `--url`, and when a turn fails because AI Gateway authentication is missing or stale, the error points you at `/model` directly. The TUI also checks at startup: a missing model-provider setup surfaces as an attention line — `⚠ 1 setup issue: model provider not linked · /model` — so the fix is visible before the first message fails, and a logged-out Vercel session surfaces the same way as `⚠ 1 setup issue: not logged in · /login` (or `Vercel CLI not found · /vc` when the CLI itself is absent). Each command's outcome hangs under it with the `⎿` connector.
+The conversation streams straight into your terminal's normal scrollback, so you keep native scrolling, copy and paste, and a transcript that persists after you exit. The scrollback holds your prompts, the agent's replies, reasoning, tool calls, nested subagents, connection-authorization prompts, and any captured `stdout`, `stderr`, or sandbox lifecycle lines.
 
-In the AI Gateway connection picker, "Connect via a project" is disabled when the Vercel CLI is missing, the CLI session is logged out, or Vercel cannot be reached. The disabled reason points to `/vc`, `/login`, or the network problem, while "Use my own key" remains available.
+Each turn renders without boxes. A colored gutter glyph marks who is speaking, tool calls collapse to a one-line summary (`✓ get_weather  city="SF" → 73°F`), and a subagent's work is indented beneath its `◆` header. When input is ready, the prompt stays bare until you type. While a turn or setup action owns the terminal, only its live status shows.
 
-The prompt input behaves like a shell line editor: `↑`/`↓` cycle through the messages you've sent this session, `←`/`→`, Home/End, and `Ctrl+A`/`Ctrl+E` move the caret, and `Ctrl+U`/`Ctrl+K`/`Ctrl+W` kill the line, the rest of the line, or the previous word. If a turn fails terminally — the server session dies or the connection drops — the TUI starts a fresh session and notes it inline so you can keep going (server-side context resets with the old session). Errors render compactly, with docs links highlighted, and a code bug escaping your agent's own code shows its stack trace dim beneath the error headline. Captured server `stdout`/`stderr` renders as dim, indented log runs behind a `│` rule — consecutive lines from the same source share one label — while sandbox lifecycle lines use their own label. Dev-server rebuilds condense further, into one status row that updates in place: `tui/setup-panel.ts changed · rebuilding…`, then `· rebuilt`. Only the latest rebuild shows, and paths shrink to their last two components. By default, `eve dev` shows `stderr` and keeps stdout and sandbox lines buffered but hidden. `/loglevel <all|stderr|sandbox|none>` switches what the transcript shows retroactively, and `--logs` sets the starting mode. Bare `/loglevel` reports the current mode. At the idle prompt, `Ctrl+L` cycles `none → all → stderr → sandbox → none` and briefly shows the selected mode in the status line; `Ctrl+R` redraws.
+A persistent line beneath the prompt or status shows the model, the session's token flow (`↑ 394.4K ↓ 4.3K`), the linked Vercel project and team (`▲ my-agent (acme)`), and a yellow `/deploy pending` marker once a channel added this session still needs `/deploy`. The Vercel segment stays hidden until the directory is linked.
 
-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.
+Errors render compactly with docs links highlighted. A code bug escaping your agent's own code shows its stack trace dim beneath the error headline. Dev-server rebuilds condense into one status row that updates in place (`tui/setup-panel.ts changed · rebuilding…`, then `· rebuilt`); only the latest rebuild shows, and paths shrink to their last two components.
 
-Density flags accept `full` / `collapsed` / `auto-collapsed` / `hidden`:
+## Slash commands
+
+Each command echoes as an invocation line, asks through a bordered panel that takes the input area's place (one question at a time, separate from the chat transcript), and finishes with a one-line `⎿` result. Loading states stay on the ephemeral status line instead of piling into the transcript.
+
+| Command     | Does                                                                                                                              |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `/model`    | Opens a configure menu that loops until Done (or Esc). See [Configure the model and provider](#configure-the-model-and-provider). |
+| `/channels` | Shows the agent's channel list and adds the one you pick. See [Add a channel](#add-a-channel).                                    |
+| `/deploy`   | Ships the agent to Vercel production, linking the directory first when it is unlinked.                                            |
+| `/loglevel` | Switches which logs the transcript shows. See [Control what logs show](#control-what-logs-show).                                  |
+| `/new`      | Starts a fresh session.                                                                                                           |
+| `/exit`     | Quits the TUI.                                                                                                                    |
+| `/help`     | Lists every command.                                                                                                              |
+
+`/model`, `/channels`, and `/deploy` manage the project and are available only when `eve dev` runs the server locally, not when connected to a remote server with `--url`.
+
+### Configure the model and provider
+
+Bare `/model` opens the configure menu. "Change model" runs the same searchable model picker setup uses (the Vercel AI Gateway catalog, pre-selected on the model the runtime is serving). A model change is written into your agent's authored source, and the command reports success only after Eve confirms the new id. `/model <provider/model-id>` applies one directly, skipping the menu.
+
+The provider row opens the provider questions: which model provider to use, and how to connect. Picking something other than Vercel AI Gateway shows wiring instructions for your own provider and stops there, leaving any existing setup untouched. For Vercel AI Gateway, you either paste your own `AI_GATEWAY_API_KEY` (saved straight to `.env.local`) or connect via a project. Connecting via a project asks for a Vercel team, opens that team's existing-project list (picking again re-links), then pulls the project's environment so an AI Gateway credential lands in `.env.local`. The dev server reloads env files automatically, with no restart needed.
+
+The provider row demands attention (a bold yellow "Configure provider" with "Required to enable the agent") until a link or gateway credential is detected, then names the connection afterward (for example "AI Gateway (Linked to my-project in my-team)"). Each action's latest outcome stays visible beneath the menu (for example "✓ Model changed to openai/gpt-5.5"). When a turn fails because AI Gateway authentication is missing or stale, the error points you at `/model` directly.
+
+### Add a channel
+
+`/channels` shows the agent's channel list. Already-registered channels render as checked, focusable rows with an "Already installed" hint. Picking one adds it (including the Slack Connect provisioning), then installs the dependencies the scaffold added so the dev server can load the new channels right away. After each addition the list repaints with the channel checked, until Done (or Esc) leaves the flow.
+
+## Keyboard shortcuts
+
+The prompt input behaves like a shell line editor.
+
+| Key                                            | Action                                                                                                            |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `Enter`                                        | Send the message.                                                                                                 |
+| `Ctrl+C`                                       | Interrupt a running turn, or quit at the prompt.                                                                  |
+| `↑` / `↓`                                      | Cycle through the messages you have sent this session.                                                            |
+| `←` / `→`, `Home` / `End`, `Ctrl+A` / `Ctrl+E` | Move the caret.                                                                                                   |
+| `Ctrl+U` / `Ctrl+K` / `Ctrl+W`                 | Kill the whole line, the rest of the line, or the previous word.                                                  |
+| `Ctrl+L`                                       | Cycle the log display mode (`none → all → stderr → sandbox → none`) and briefly show the mode in the status line. |
+| `Ctrl+R`                                       | Redraw the screen.                                                                                                |
+
+If a turn fails terminally (the server session dies or the connection drops), the TUI starts a fresh session and notes it inline so you can keep going. Server-side context resets with the old session.
+
+## Answer the agent inline
+
+When the agent needs something from you, the TUI asks inline.
+
+- Tool approvals are a `y` or `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 finish the flow.
+
+## Control what logs show
+
+By default, `eve dev` shows `stderr` and keeps stdout and sandbox lines buffered but hidden. Captured server `stdout` and `stderr` render as dim, indented log runs behind a `│` rule (consecutive lines from the same source share one label), while sandbox lifecycle lines use their own label.
+
+- `/loglevel <all|stderr|sandbox|none>` switches what the transcript shows, retroactively. Bare `/loglevel` reports the current mode.
+- `--logs <all|stderr|sandbox|none>` sets the starting mode at launch (default `stderr`).
+- `Ctrl+L` at the idle prompt cycles `none → all → stderr → sandbox → none`.
+
+## Display flags
+
+Density flags control how much of each section renders. They accept `full`, `collapsed`, `auto-collapsed`, or `hidden`.
 
 ```bash
 eve dev --tools full --assistant-response-stats tokens --context-size 200000
 ```
 
-Other useful flags: `--subagents`, `--reasoning`, `--logs <all|stderr|sandbox|none>`, `--host`/`--port`, and `--no-ui` (headless, also the automatic fallback when stdout isn't a TTY).
+| Flag                                | Values                                             | Effect                                                  |
+| ----------------------------------- | -------------------------------------------------- | ------------------------------------------------------- |
+| `--tools <mode>`                    | `full` / `collapsed` / `auto-collapsed` / `hidden` | How tool calls render (default `auto-collapsed`).       |
+| `--reasoning <mode>`                | `full` / `collapsed` / `auto-collapsed` / `hidden` | How reasoning renders (default `full`).                 |
+| `--subagents <mode>`                | `full` / `collapsed` / `auto-collapsed` / `hidden` | How subagent sections render.                           |
+| `--connection-auth <mode>`          | `full` / `collapsed` / `auto-collapsed` / `hidden` | How connection authorization renders.                   |
+| `--assistant-response-stats <mode>` | `tokens` / `tokensPerSecond`                       | Which statistic the assistant header shows.             |
+| `--context-size <tokens>`           | a token count                                      | Model context window size, shown as a usage percentage. |
+| `--logs <mode>`                     | `all` / `stderr` / `sandbox` / `none`              | Which server and agent logs to show (default `stderr`). |
+
+Connection flags: `--host` and `--port` bind the local server, and `--no-ui` runs headless (also the automatic fallback when stdout is not a TTY). See the [CLI](../reference/cli) for the full flag list.
 
 ## 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:
+Pass a URL and the TUI talks to a running deployment instead of starting a local server, which is handy for a Vercel preview or your production app.
 
 ```bash
 eve dev https://<your-app>
@@ -48,5 +120,5 @@ The bare URL is shorthand for `--url`. `--host`, `--port`, and `--no-ui` are ign
 
 ## What to read next
 
-- [instrumentation.ts](./instrumentation): OpenTelemetry, hooks, and the error catalog.
+- [Observability](./instrumentation): OpenTelemetry, run tags, and common failures.
 - [CLI](../reference/cli): every command and flag.

package/docs/guides/dynamic-capabilities.md

@@ -3,13 +3,13 @@ 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.
+`defineDynamic` resolves tools, skills, and instructions at runtime from a session event instead of declaring them up front. Reach for it when the right capabilities aren't known until the session starts, because they 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:
+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";
@@ -33,6 +33,10 @@ export default defineDynamic({
 });
 ```
 
+### `execute` must be an inline function
+
+Write `execute` as an inline function expression, arrow, or method shorthand placed directly as the property value. The bundler transform does not detect `execute: myFn` or `execute: makeFn()`, so those tools work on the first step but do not survive replay (re-running a step after a crash or resume; see [Execution model & durability](../concepts/execution-model-and-durability)). On later steps the transform reconstructs each `execute` from its stored closure variables instead of re-running the resolver, which is why it has to be inline.
+
 ### Naming
 
 | Return shape              | File                       | Tool name(s)                      |
@@ -51,33 +55,45 @@ A single return produces one tool named after the file slug, identical to a stat
 | `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.
+When a stream event fires, three things happen in order.
+
+1. The channel adapter handler runs and the event is written to the durable stream.
+2. Stream-event [hooks](./hooks) fire.
+3. 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"
+import { defineDynamic, defineTool } from "eve/tools";
+import { z } from "zod";
+import { runReadOnly, searchCatalog } from "../lib/catalog.js";
+
 export default defineDynamic({
   events: {
     "session.started": async (_event, ctx) => ({
       query: defineTool({
-        /* ... */
+        description: "Run a read-only query.",
+        inputSchema: z.object({ sql: z.string() }),
+        execute: ({ sql }) => runReadOnly(sql),
       }),
     }),
     // On each turn, re-resolve. Replaces this file's session.started tools for later calls.
     "turn.started": async (_event, ctx) => ({
       search: defineTool({
-        /* ... */
+        description: "Search the catalog.",
+        inputSchema: z.object({ term: z.string() }),
+        execute: ({ term }) => searchCatalog(term),
       }),
     }),
   },
 });
 ```
 
-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.
+Resolvers across files run concurrently.
 
 ## Dynamic skills
 

package/docs/guides/dynamic-workflows.md

@@ -3,11 +3,11 @@ 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.
+The experimental `Workflow` tool lets the model write JavaScript that coordinates the agent's own subagents as a single durable step. The program can run them in sequence, feed one result into the next, fan out over a list, and combine the results. You enable the capability and the model decides and runs the orchestration. It is the agents-only slice of [code mode](../agent-config#other-defineagent-fields) (the broader `codeMode` flag that routes all of an agent's tools through model-authored JavaScript).
 
-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.
+A single turn can already call several subagents, and parallel tool calls dispatch concurrently. What a workflow adds is _programmatic_ coordination. The program decides how many subagents to run based on an earlier result, which output feeds which call, and how to combine everything. That is logic the model cannot express as a few one-off calls.
 
-## Enable it
+## Enable the Workflow tool
 
 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`.
 
@@ -26,27 +26,48 @@ export default defineAgent({
 });
 ```
 
-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.
+When asked for a weekly business review, the model picks the metrics, runs one `analyst` per metric in parallel, and combines the findings. The program below is the kind of JavaScript the model authors. It fans `analyst` out over a runtime-decided list of metrics and merges the results:
 
-## What it can orchestrate
+```js
+const metrics = ["revenue", "signups", "churn"];
+const findings = await Promise.all(
+  metrics.map((metric) => tools.analyst({ message: `Summarize last week's ${metric}.` })),
+);
+return findings.join("\n\n");
+```
+
+Each `tools.analyst(...)` call dispatches a child subagent, so the parent stream records one `subagent.called` per metric and one `subagent.completed` as each finishes:
+
+```json
+{ "type": "subagent.called", "data": { "name": "analyst", "toolName": "analyst", "callId": "call_1", "childSessionId": "ses_a1", "sequence": 0 } }
+{ "type": "subagent.called", "data": { "name": "analyst", "toolName": "analyst", "callId": "call_2", "childSessionId": "ses_a2", "sequence": 1 } }
+{ "type": "subagent.called", "data": { "name": "analyst", "toolName": "analyst", "callId": "call_3", "childSessionId": "ses_a3", "sequence": 2 } }
+{ "type": "subagent.completed", "data": { "subagentName": "analyst", "callId": "call_1", "output": "..." } }
+{ "type": "subagent.completed", "data": { "subagentName": "analyst", "callId": "call_2", "output": "..." } }
+{ "type": "subagent.completed", "data": { "subagentName": "analyst", "callId": "call_3", "output": "..." } }
+```
+
+## What a workflow 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.
+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 is the whole list. No files, network, shell, skills, or connections. A workflow is 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.
+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, so there is no `process`, no `globalThis` from the agent, and 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.
+That is an allowlist, not a denylist. The sandbox cannot read files, open a socket, or see an environment variable because those are not 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 exactly like a direct delegation. The orchestration glue stays inside the sandbox.
 
-## How it behaves
+## Durability, approvals, and observability
 
-- **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.
+- **Durable.** The whole orchestration counts as one step. Subagents dispatched together run concurrently, and if a run parks (suspends durably without holding compute; see [Execution model & durability](../concepts/execution-model-and-durability)) on a long-running or human-gated child, it resumes where it left off after a restart.
+- **Approval-safe.** A subagent that needs human approval (HITL, human-in-the-loop) mid-run surfaces its request to the user, and the workflow picks back up once that is 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.
+[Code mode](../agent-config#other-defineagent-fields) is the broader version, where the model drives _all_ of an agent's tools (files, shell, web, and agents) from JavaScript. A workflow covers only the subagents. The two do not interfere. Enabling the `Workflow` tool leaves code mode untouched, and an agent can run both at once.
+
+`codeMode` is experimental and may change or be removed.
 
 ## What to read next
 

package/docs/guides/frontend/nextjs.mdx

@@ -3,7 +3,13 @@ title: "Next.js"
 description: "Run an Eve agent and a Next.js app as one project with withEve."
 ---
 
-`eve/next` lets you ship a Next.js frontend and an Eve agent as a single project. Wrap your config with `withEve()` and the two run together: one dev server, one Vercel deploy. [`useEveAgent`](./overview) finds the mounted routes on its own, so there's no CORS to fight and no URL env vars to keep in sync.
+`eve/next` ships a Next.js frontend and an Eve agent as a single project. Wrap your config with `withEve()` to run both from one dev server and one Vercel deploy. [`useEveAgent`](./overview) finds the mounted routes on its own, so there's no CORS to configure and no URL env vars to keep in sync.
+
+## Prerequisites
+
+- The `eve` package installed in your project (`npm install eve@latest`).
+- An existing Eve agent directory. If you don't have one, start from [Getting started](../../getting-started).
+- A Next.js app to mount the agent in.
 
 ## Wrap the Next.js config
 
@@ -16,7 +22,7 @@ const nextConfig: NextConfig = {};
 export default withEve(nextConfig);
 ```
 
-By default `withEve()` looks for an `agent/` folder next to your Next.js project root. If the agent lives somewhere else, point at it with `eveRoot`:
+By default `withEve()` looks for an `agent/` folder inside your Next.js project root. If the agent lives somewhere else, point at it with `eveRoot`:
 
 ```ts
 export default withEve(nextConfig, {
@@ -28,15 +34,14 @@ export default withEve(nextConfig, {
 
 All fields are optional.
 
-| Option                  | Type      | Default                | Purpose                                                                                                                                                 |
-| ----------------------- | --------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `eveRoot`               | `string`  | Next.js app root       | Path to the Eve app root, relative to `process.cwd()` unless absolute. Set it when the agent lives outside the Next.js project.                         |
-| `eveBuildCommand`       | `string`  | `"eve build"`          | Build command for the generated Eve Vercel service. Use it when the Eve service needs project-specific prework, without changing the Next.js build.     |
-| `configureVercelOutput` | `boolean` | `true`                 | Set to `false` to skip creating or updating `.vercel/output/config.json`. By default `withEve` writes the `experimentalServices` entries for both apps. |
-| `servicePrefix`         | `string`  | `"/_eve_internal/eve"` | Private Vercel route namespace for the Eve service. Must match the Eve service's mount in your Vercel Build Output config when you set it manually.     |
-| `devServerTimeoutMs`    | `number`  | `180000`               | Maximum time to wait for the Eve development server to become available.                                                                                |
+| Option               | Type     | Default                | Purpose                                                                                                                                             |
+| -------------------- | -------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eveRoot`            | `string` | Next.js app root       | Path to the Eve app root, relative to `process.cwd()` unless absolute. Set it when the agent lives outside the Next.js project.                     |
+| `eveBuildCommand`    | `string` | `"eve build"`          | Build command for the generated Eve Vercel service. Use it when the Eve service needs project-specific prework, without changing the Next.js build. |
+| `servicePrefix`      | `string` | `"/_eve_internal/eve"` | Private Vercel route namespace for the Eve service. Must match the Eve service's mount in your Vercel Build Output config when you set it manually. |
+| `devServerTimeoutMs` | `number` | `180000`               | Maximum time to wait for the Eve development server to become available.                                                                            |
 
-For unusually slow cold starts, increase the development timeout:
+For slow cold starts, increase the development timeout:
 
 ```ts
 export default withEve(nextConfig, {
@@ -46,7 +51,7 @@ export default withEve(nextConfig, {
 
 ## Call the hook
 
-With `withEve()` in `next.config.ts`, the Eve routes are same-origin, so client code can call [`useEveAgent`](./overview) without naming a host. Cookie-based auth just works, whether that's Auth.js or any session cookie, since the browser already sends those cookies on every Eve request. For non-cookie schemes, attach the credentials yourself:
+With `withEve()` in `next.config.ts`, the Eve routes are same-origin, so client code can call [`useEveAgent`](./overview) without naming a host. Cookie-based auth (Auth.js or any session cookie) needs no extra wiring, since the browser already sends those cookies on every Eve request. For non-cookie schemes, attach the credentials yourself:
 
 ```tsx
 const agent = useEveAgent({
@@ -56,7 +61,16 @@ const agent = useEveAgent({
 });
 ```
 
-Before deploying a user-facing app, add `agent/channels/eve.ts` so production requests run your app's auth policy. See [Channels](../../channels/overview) and [Auth & route protection](../auth-and-route-protection).
+The default Eve channel is fail-closed. With no `agent/channels/eve.ts` authored, Eve registers `eveChannel({ auth: [localDev(), vercelOidc()] })`: `localDev()` opens the routes on localhost, `vercelOidc()` admits Vercel OIDC callers in production, and everything else gets a `401`. To run your app's own auth policy, add `agent/channels/eve.ts`:
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel } from "eve/channels/eve";
+import { localDev, vercelOidc } from "eve/channels/auth";
+
+export default eveChannel({ auth: [localDev(), vercelOidc()] });
+```
+
+For a public demo, use `none()` (also from `eve/channels/auth`) to skip authentication. See [Channels](../../channels/overview) and [Auth & route protection](../auth-and-route-protection).
 
 ## Dev vs deploy topology
 
@@ -69,13 +83,13 @@ Before deploying a user-facing app, add `agent/channels/eve.ts` so production re
   });
   ```
 
-- **Local production build.** `next build && next start` proxies Eve routes to `http://127.0.0.1:4274`. Change the port with `EVE_NEXT_PRODUCTION_PORT`:
+- **Local production build.** `next build && next start` serves the Eve runtime from its built `.output/server/index.mjs` on a stable local port (`4274`) and proxies the Eve routes to it. Run `eve build` first so that output exists. Change the port with `EVE_NEXT_PRODUCTION_PORT`:
 
   ```bash
   EVE_NEXT_PRODUCTION_PORT=5000 npm run build && npm start
   ```
 
-- **Non-Vercel hosts.** If the Eve service lives on a separate origin, tell Next.js where to find it with `EVE_NEXT_PRODUCTION_ORIGIN`:
+- **Non-Vercel hosts.** When the Eve service lives on a separate origin, tell Next.js where to find it with `EVE_NEXT_PRODUCTION_ORIGIN`:
 
   ```bash
   EVE_NEXT_PRODUCTION_ORIGIN=https://agent.example.com npm run build

package/docs/guides/frontend/nuxt.mdx

@@ -3,7 +3,13 @@ title: "Nuxt"
 description: "Run an Eve agent and a Nuxt app as one project with the eve/nuxt module."
 ---
 
-The `eve/nuxt` module folds a Nuxt frontend and an Eve agent into a single project: one dev server, one Vercel deploy. The auto-imported [`useEveAgent`](./use-eve-agent-vue) composable finds the mounted routes on its own, so you skip the usual CORS headaches and URL env vars.
+The `eve/nuxt` module runs a Nuxt frontend and an Eve agent as a single project from one dev server and one Vercel deploy. The auto-imported [`useEveAgent`](./use-eve-agent-vue) composable finds the mounted routes on its own, so there's no CORS to configure and no URL env vars to keep in sync.
+
+## Prerequisites
+
+- The `eve` package installed in your project (`npm install eve@latest`).
+- An existing Eve agent directory. If you don't have one, start from [Getting started](../../getting-started).
+- A Nuxt app to mount the agent in.
 
 ## Register the module
 
@@ -24,9 +30,11 @@ export default defineNuxtConfig({
 });
 ```
 
+The `eve` key accepts only two options, `eveRoot` and `eveBuildCommand`.
+
 ## Call the composable
 
-`useEveAgent` (`eve/vue`) is auto-imported, so a component can call it without an explicit import and without naming a host:
+`useEveAgent` (`eve/vue`) is auto-imported, so a component calls it without an explicit import and without naming a host:
 
 ```vue
 <script setup lang="ts">
@@ -52,7 +60,16 @@ async function handleSubmit() {
 </template>
 ```
 
-Out of the box the module gives Eve a framework default channel. When you want to pick 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](../auth-and-route-protection).
+The default Eve channel is fail-closed. With no `agent/channels/eve.ts` authored, Eve registers `eveChannel({ auth: [localDev(), vercelOidc()] })`: `localDev()` opens the routes on localhost, `vercelOidc()` admits Vercel OIDC callers in production, and everything else gets a `401`. To run your own auth policy, add `agent/channels/eve.ts`:
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel } from "eve/channels/eve";
+import { localDev, vercelOidc } from "eve/channels/auth";
+
+export default eveChannel({ auth: [localDev(), vercelOidc()] });
+```
+
+For a public demo, use `none()` (also from `eve/channels/auth`) to skip authentication. See [Channels](../../channels/overview) and [Auth & route protection](../auth-and-route-protection).
 
 ## Dev vs deploy topology
 
@@ -68,7 +85,7 @@ Out of the box the module gives Eve a framework default channel. When you want t
   });
   ```
 
-- **Non-Vercel hosts.** Point Nuxt at a separate Eve origin with `EVE_NUXT_PRODUCTION_ORIGIN`. To override the local port (it defaults to `4274`), use `EVE_NUXT_PRODUCTION_PORT`:
+- **Non-Vercel hosts.** Point Nuxt at a separate Eve origin with `EVE_NUXT_PRODUCTION_ORIGIN`. To override the local port (default `4274`), use `EVE_NUXT_PRODUCTION_PORT`:
 
   ```bash
   EVE_NUXT_PRODUCTION_ORIGIN=https://agent.example.com npm run build

package/docs/guides/frontend/overview.mdx

@@ -3,22 +3,22 @@ title: "Overview"
 description: "Put an Eve agent behind a browser chat UI with useEveAgent."
 ---
 
-The frontend helpers put a browser chat or agent UI on top of an Eve agent. `useEveAgent()` does the heavy lifting: it opens a durable session, sends turns, streams the reply back, and turns the raw event stream into render-ready state. React is the reference implementation, and [Vue](./use-eve-agent-vue) and [Svelte](./use-eve-agent-svelte) ship the same surface.
+The frontend helpers put a browser chat or agent UI on top of an Eve agent. `useEveAgent()` opens a durable session, sends turns, streams the reply back, and turns the raw event stream into render-ready state. React is the reference implementation; [Vue](./use-eve-agent-vue) and [Svelte](./use-eve-agent-svelte) ship the same surface.
 
 ## The integration model
 
-A browser UI is just a client of the agent's HTTP routes (the [Eve channel](../../channels/overview)). Two layers wire it up:
+A browser UI is a client of the agent's HTTP routes (the [Eve channel](../../channels/overview)). Two layers wire it up:
 
 - **The framework integration** mounts the Eve routes on your app's origin, so the browser never crosses a CORS boundary or reads an env var to find the agent. Pick yours: [Next.js](./nextjs) (`withEve`), [Nuxt](./nuxt) (the `eve/nuxt` module), or [SvelteKit](./sveltekit) (the `eveSvelteKit` Vite plugin). On any other stack the hook talks to same-origin `/eve/v1/*` routes directly, or you pass an explicit `host`.
 - **The hook** (`useEveAgent`) holds the session state, streaming, errors, and composer status. It defaults to same-origin Eve routes such as `/eve/v1/session`.
 
-For a guided setup, the [Guides](/docs/skills/eve-add-next) walk through the wiring step by step: [add a Next.js frontend to an existing Eve agent](/docs/skills/eve-add-next), or [add Eve to an existing Next.js app](/docs/skills/eve-add-agent).
+The per-framework pages below walk through the wiring step by step: [Next.js](./nextjs), [Nuxt](./nuxt), and [SvelteKit](./sveltekit).
 
 For scripts, server-to-server calls, evals, tests, or custom clients that do not need framework UI state, use the [TypeScript SDK](../client/overview) directly.
 
 ## Basic chat (React)
 
-The hook lives in `eve/react`. Render `data.messages`, gate the composer on `status`, and send text with `send`. That's the whole loop:
+The hook lives in `eve/react`. Render `data.messages`, gate the composer on `status`, and send text with `send`:
 
 ```tsx
 "use client";
@@ -72,7 +72,7 @@ export function Chat() {
 | `stop`    | Abort the active request.                                                      |
 | `reset`   | Clear local events, data, errors, and the local session cursor.                |
 
-Most chat UIs only need `data.messages` and `status`. Drop down to `events` when you want to render lower-level activity (tool calls, reasoning deltas) that the default reducer doesn’t surface.
+Most chat UIs only need `data.messages` and `status`. Drop down to `events` to render lower-level activity such as tool calls and reasoning deltas that the default reducer doesn't surface.
 
 `data.messages` are `EveMessage[]` following the AI SDK `UIMessage` convention, so they drop straight into any AI SDK UI primitive that accepts a `UIMessage[]`. Parts include user text, assistant text, reasoning, tool calls, tool results, and input requests.
 
@@ -96,7 +96,7 @@ await agent.send({
 });
 ```
 
-Assistant text, reasoning, tool calls, and tool results stream into `data` as they arrive, and `status` moves from `ready` to `submitted` to `streaming` and back. Call `stop()` to abort the active request. Call `reset()` to clear local state so the next send starts a fresh durable session.
+Assistant text, reasoning, tool calls, and tool results stream into `data` as they arrive, and `status` moves from `ready` to `submitted` to `streaming` and back. Call `stop()` to abort the active request, and `reset()` to clear local state so the next send starts a fresh durable session.
 
 ## Human-in-the-loop prompts
 
@@ -115,11 +115,11 @@ if (request) {
 }
 ```
 
-`request.prompt` and `request.options` give you what you need to render the approve and deny UI. The default reducer marks the part as responded right away, then updates it again once Eve streams the resumed result.
+`request.prompt` and `request.options` give you what you need to render the approve and deny UI. The default reducer marks the part as responded immediately, then updates it again once Eve streams the resumed result.
 
 ## Attach page context per turn
 
-`clientContext` adds ephemeral context for the next model call and nothing more. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, so it never dispatches a turn on its own and never lands in durable session history. Pass it directly to `send()`:
+`clientContext` adds ephemeral context for the next model call only. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, so it never dispatches a turn on its own and never lands in durable session history. Pass it directly to `send()`:
 
 ```tsx
 await agent.send({
@@ -182,11 +182,11 @@ const agent = useEveAgent({ reducer: toolCounter });
 // agent.data is ToolLog
 ```
 
-`reduce(data, event)` receives both authoritative Eve stream events and client projection events (`client.message.submitted`, `client.message.failed`, `client.input.responded`). Handle the client events too if you want optimistic and HITL state in your projection. Otherwise, just return `data` unchanged for them.
+`reduce(data, event)` receives both authoritative Eve stream events and client projection events (`client.message.submitted`, `client.message.failed`, `client.input.responded`). Handle the client events too if you want optimistic and HITL state in your projection. Otherwise, return `data` unchanged for them.
 
 ## Resumable sessions
 
-The browser conversation lives durably on the server. Persist the `session` cursor and you can pick it back up after a reload:
+The browser conversation lives durably on the server. Persist the `session` cursor to pick it back up after a reload:
 
 ```tsx
 const [initialSession] = useState(() => {
@@ -231,4 +231,4 @@ const agent = useEveAgent({
 - [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming): the event stream and session cursor
 - [Channels](../../channels/overview): the HTTP routes the hook talks to
 - [TypeScript SDK](../client/overview): the lower-level client underneath the frontend hooks
-- [Guides](/docs/skills/eve-add-next): step-by-step guides for wiring Eve into Next.js
+- [Next.js](./nextjs): step-by-step setup for wiring Eve into a Next.js app

package/docs/guides/frontend/sveltekit.mdx

@@ -3,7 +3,13 @@ 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.
+`eve/sveltekit` runs a SvelteKit frontend and an Eve agent as one project instead of two services. 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. There's no CORS to configure and no URL env vars to keep in sync.
+
+## Prerequisites
+
+- The `eve` package installed in your project (`npm install eve@latest`).
+- An existing Eve agent directory. If you don't have one, start from [Getting started](../../getting-started).
+- A SvelteKit app to mount the agent in.
 
 ## Register the Vite plugin
 
@@ -32,6 +38,8 @@ export default defineConfig({
 });
 ```
 
+The plugin accepts only two options, `eveRoot` and `eveBuildCommand`.
+
 ## 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:
@@ -61,11 +69,20 @@ With the plugin in `vite.config.ts`, components call [`useEveAgent`](./use-eve-a
 </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](../auth-and-route-protection).
+The default Eve channel is fail-closed. With no `agent/channels/eve.ts` authored, Eve registers `eveChannel({ auth: [localDev(), vercelOidc()] })`: `localDev()` opens the routes on localhost, `vercelOidc()` admits Vercel OIDC callers in production, and everything else gets a `401`. To set your own auth policy, add `agent/channels/eve.ts`:
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel } from "eve/channels/eve";
+import { localDev, vercelOidc } from "eve/channels/auth";
+
+export default eveChannel({ auth: [localDev(), vercelOidc()] });
+```
+
+For a public demo, use `none()` (also from `eve/channels/auth`) to skip authentication. See [Channels](../../channels/overview) and [Auth & route protection](../auth-and-route-protection).
 
 ## Dev vs deploy topology
 
-- **Local dev.** `npm run 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. `npm run build && npm run preview` behaves the same: the preview server gets its own Eve route proxy and either reuses the shared Eve server or starts one.
+- **Local dev.** `npm run 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. `npm run build && npm run preview` behaves the same way: 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