eve 0.44.3 → 0.45.0

package/docs/concepts/built-in-tools.md

@@ -3,7 +3,7 @@ title: "Built-in Tools"
 description: "The default and opt-in tools eve provides, including Workflow, glob, grep, and sleep."
 ---
 
-eve provides a default tool set for every agent and additional framework tools you can add with one file. Use this page to review what the model can call, opt into more capabilities, or override and disable defaults. For custom tools, see [Tools](../tools).
+eve provides a default tool set for every agent and additional tools you can add with one file. Each default occupies the same `agent/tools/<name>.ts` slot you would author yourself, so an authored definition replaces it and `disableTool()` removes it. Use this page to review what the model can call, opt into more capabilities, or override and disable defaults. For custom tools, see [Tools](../tools).
 
 ## Default tools
 
@@ -30,8 +30,9 @@ Notes:
 
 - **`agent`** is available only in the root session. Its child uses the root's instructions, tools, connections, and sandbox, but starts with fresh conversation history and fresh [state](./state). The child receives neither `agent` nor `Workflow`; declared subagents do not receive the built-in `agent` either. See [Subagents](../subagents).
 - **`load_skill`** only pulls instructions into context. It adds no new execution surface, because behavior still comes from the tools the agent already has.
-- **`connection_search`** surfaces a connection's tools by their qualified name (e.g. `linear__list_issues`), which the model can then call directly. It's registered only when the agent has connections.
+- **`connection_search`** surfaces a connection's tools by their qualified name (e.g. `linear__list_issues`), which the model can then call directly. The model sees it only when the agent has connections.
 - **`web_search`** has no local executor; the provider runs it. AI Gateway models use Exa by default. To use Parallel instead, export `webSearch({ provider: "parallel" })` from `agent/tools/web_search.ts`. Direct provider models continue to use their native search implementation. To supply your own implementation, override it with `defineTool()`.
+- **`web_fetch`** follows up to ten redirects, rechecking every destination for SSRF safety. Non-success HTTP responses return a plain-text failure result with the response body when available instead of failing the tool call.
 
 Review these default tools before production use. Disable, wrap, restrict, or require approval for any tool that can access the filesystem, network, shell, or sensitive data.
 
@@ -39,28 +40,24 @@ Review these default tools before production use. Disable, wrap, restrict, or re
 
 Some framework-provided tools stay out of the default set. Add the corresponding file when your agent needs one:
 
-| Tool       | Definition to export                       | Purpose                                            |
-| ---------- | ------------------------------------------ | -------------------------------------------------- |
-| `glob`     | `defineGlobTool()` from `eve/tools`        | Find sandbox files by glob pattern.                |
-| `grep`     | `defineGrepTool()` from `eve/tools`        | Search sandbox file contents by regex.             |
-| `Workflow` | `experimental_workflow()` from `eve/tools` | Orchestrate root-agent copies from generated code. |
-| `sleep`    | `sleep()` from `eve/tools/sleep`           | Pause and durably resume the current turn.         |
+| Tool       | Definition to export                                | Purpose                                            |
+| ---------- | --------------------------------------------------- | -------------------------------------------------- |
+| `glob`     | `glob` from `eve/tools/glob`                        | Find sandbox files by glob pattern.                |
+| `grep`     | `grep` from `eve/tools/grep`                        | Search sandbox file contents by regex.             |
+| `Workflow` | `experimental_workflow()` from `eve/tools/workflow` | Orchestrate root-agent copies from generated code. |
+| `sleep`    | `sleep()` from `eve/tools/sleep`                    | Pause and durably resume the current turn.         |
 
 For example, add file discovery and content search with two files:
 
 ```ts title="agent/tools/glob.ts"
-import { defineGlobTool } from "eve/tools";
-
-export default defineGlobTool();
+export { glob as default } from "eve/tools/glob";
 ```
 
 ```ts title="agent/tools/grep.ts"
-import { defineGrepTool } from "eve/tools";
-
-export default defineGrepTool();
+export { grep as default } from "eve/tools/grep";
 ```
 
-The filename supplies the model-facing tool name. You can pass a custom `description` to either helper. The tools run against the agent's sandbox and use the same schemas, results, and error behavior as eve's framework implementations.
+The filename supplies the model-facing tool name. The tools run against the agent's sandbox and use the same schemas, results, and error behavior as eve's framework implementations. Wrap either definition with `defineTool({ ...glob, description: "..." })` or `defineTool({ ...grep, description: "..." })` when you need to change its description or approval policy.
 
 The sections below cover `Workflow` and `sleep` in more detail.
 
@@ -70,7 +67,7 @@ Author a tool at the same slug and it takes over the built-in of that name. The
 
 ```ts title="agent/tools/write_file.ts"
 import { defineTool } from "eve/tools";
-import { writeFile } from "eve/tools/defaults";
+import { writeFile } from "eve/tools/write_file";
 
 export default defineTool({
   ...writeFile, // keep the default description, schema, and executor
@@ -81,12 +78,25 @@ export default defineTool({
 });
 ```
 
-Framework tool definitions are importable from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `todo`, `loadSkill`), so you can spread, wrap, or patch them. Importing a definition does not add it to an agent; export it from the corresponding `agent/tools/*.ts` file. Skip the spread and your replacement owns its own context. A fresh `defineTool` for `todo` won't inherit the framework's durable state key.
+Import each reusable definition from its own subpath:
+
+| Definition  | Import                 | Registered by default |
+| ----------- | ---------------------- | --------------------- |
+| `bash`      | `eve/tools/bash`       | Yes                   |
+| `readFile`  | `eve/tools/read_file`  | Yes                   |
+| `writeFile` | `eve/tools/write_file` | Yes                   |
+| `todo`      | `eve/tools/todo`       | Yes                   |
+| `webFetch`  | `eve/tools/web_fetch`  | Yes                   |
+| `loadSkill` | `eve/tools/load_skill` | Yes                   |
+| `glob`      | `eve/tools/glob`       | No                    |
+| `grep`      | `eve/tools/grep`       | No                    |
+
+Importing a definition does not add it to an agent; export it from the corresponding `agent/tools/*.ts` file. Skip the spread and your replacement owns its own context. A fresh `defineTool` for `todo` does not inherit the default's durable state key.
 
 Provider-managed web search has a dedicated configuration helper instead of an executable default:
 
 ```ts title="agent/tools/web_search.ts"
-import { webSearch } from "eve/tools";
+import { webSearch } from "eve/tools/web_search";
 
 export default webSearch({ provider: "parallel" });
 ```
@@ -111,7 +121,7 @@ If the filename matches no known framework tool, resolution fails instead of sil
 
 Three moves shape the harness. The right one depends on whether the model should keep the built-in capability.
 
-- **Override** when you want the same capability with different behavior. Spread the default from `eve/tools/defaults` and wrap it (logging, an extra guard, a different backend), and the model still sees a tool by that name. Spreading keeps the default's description, schema, and any framework state, such as the `todo` tool's durable state key. Drop the spread and your replacement owns its own context, losing that wiring.
+- **Override** when you want the same capability with different behavior. Import its definition from the matching `eve/tools/<name>` subpath and wrap it (logging, an extra guard, or a different backend), and the model still sees a tool by that name. Spreading keeps the default's description, schema, and any framework state, such as the `todo` tool's durable state key. Drop the spread and your replacement owns its own context, losing that wiring.
 - **Disable** when the model should not have the capability at all. A `disableTool()` sentinel removes the built-in, and the model never sees it. Reach for this to lock down `bash` or `web_fetch` in an agent that should not run shell commands or fetch arbitrary URLs.
 - **Author a new tool** when you want a capability the harness does not ship. Give it a fresh slug under `agent/tools/` and it joins the built-ins instead of replacing one. See [Tools](../tools) for the authoring model.
 
@@ -128,7 +138,7 @@ A single turn can already call several subagents, and parallel tool calls dispat
 Export the experimental Workflow definition from `agent/tools/workflow.ts`. The helper name carries the "experimental" warning, but the tool the model actually sees is named `Workflow`.
 
 ```ts title="agent/tools/workflow.ts"
-import { experimental_workflow } from "eve/tools";
+import { experimental_workflow } from "eve/tools/workflow";
 
 export default experimental_workflow();
 ```
@@ -176,7 +186,7 @@ Workflow orchestration is capped in two independent ways.
 **Per-program call budget.** One Workflow program may dispatch at most `maxSubagents` subagent calls in total, counted across the whole program — sequential and parallel calls alike. Configure it on `experimental_workflow`; the default is 100. Calls beyond the budget do not start a child session; they resolve inside the program with a `WORKFLOW_SUBAGENT_LIMIT_REACHED` error result, and the budget is stated in the tool's description so the model sizes its fan-out to fit.
 
 ```ts title="agent/tools/workflow.ts"
-import { experimental_workflow } from "eve/tools";
+import { experimental_workflow } from "eve/tools/workflow";
 
 export default experimental_workflow({ maxSubagents: 4 });
 ```

package/docs/concepts/sessions-runs-and-streaming.md

@@ -244,7 +244,9 @@ Start with the [Client SDK](../guides/client/overview) guide. It covers basic us
 
 ## Inspect the agent over HTTP
 
-`GET /eve/v1/info` returns a JSON inspection snapshot for the running agent: model, static instructions, authored and framework tools, skills, channels, schedules, subagents, sandbox, connections, hooks, workflow, and workspace metadata. Static instructions are an ordered array whose entries expose `content` and `role`; dynamic resolver output is runtime context and is not included. The route uses the resolved `eveChannel()` auth when `agent/channels/eve.ts` authors one; otherwise it falls back to the framework default of Vercel OIDC plus local development access.
+`GET /eve/v1/info` returns agent-info version 3, a JSON inspection snapshot of the effective compiled agent. It reports the selected config; active tools, instructions, skills, channels, schedules, sandbox, connections, hooks, and instrumentation with explicit source ownership; dynamic resolvers separately from their session-specific output; local and remote agents in separate collections; prepared built-in effects; and shadowed or disabled source diagnostics. Channel routes appear in the same effective order used by the HTTP host. Static instructions remain an ordered array whose entries expose `content` and `role`.
+
+The info route belongs to the selected `channels/eve.ts` source and uses its resolved auth policy. Without an authored replacement, eve selects the default channel source with Vercel OIDC, local development access, and the production placeholder. Replacing or disabling that source replaces or removes the info route too; no native fallback serves it.
 
 ```bash
 curl http://127.0.0.1:2000/eve/v1/info

package/docs/connections/overview.mdx

@@ -4,7 +4,7 @@ description: "Expose external MCP and OpenAPI servers to the model, with connect
 url: /connections
 ---
 
-A connection wires an agent into an external server you don't author, either an MCP server (Linear, GitHub, a warehouse) or any HTTP API with an OpenAPI document. eve handles the parts you'd otherwise hand-roll, discovering the remote tools, surfacing them to the model, and brokering auth.
+A connection wires an agent into an external server you don't author, either an MCP server (Linear, GitHub, a warehouse) or any HTTP API with an OpenAPI document. eve handles the parts you'd otherwise hand-roll, discovering the remote tools, surfacing them to the model, and brokering auth. To instead let eve communicate with users through an external service, use a [channel](/docs/channels/overview).
 
 Connections live under `agent/connections/`. The runtime name comes from the filename, so `agent/connections/linear.ts` registers as `"linear"`. The model never sees a connection's URL or credentials. It discovers tools through the built-in `connection_search` and calls them by their qualified name, `<connection>__<tool>` (e.g. `linear__list_issues`).
 

package/docs/extensions.md

@@ -273,7 +273,7 @@ Production `eve build` expects the extension distribution to exist already. Keep
 
 ### Override a contribution
 
-Use a directory mount to replace or remove an extension contribution. Put the mount declaration in `extension.ts` and add overrides beside it:
+Use a directory mount to keep overrides beside the mount declaration. Put the declaration in `extension.ts` and add overrides beside it:
 
 ```
 agent/extensions/crm/
@@ -307,7 +307,7 @@ export default disableTool();
 
 Hooks and instruction fragments are additive, so they cannot be replaced. To replace a dynamic tool, use a dynamic definition in the same slot; dynamic tools win over same-named static tools at runtime. `disableTool()` removes either kind.
 
-The `crm__` prefix is reserved for this directory mount. A consumer cannot override the extension from `agent/tools/`, `agent/connections/`, `agent/subagents/`, or another agent-root slot.
+You can also place an override in the corresponding agent-root slot by using the final qualified name. For example, `agent/tools/crm__search.ts` replaces `tools/search.ts` from the extension package or its directory override. Application sources have the highest precedence, so an agent-root override wins when both forms exist.
 
 ### Use an extension tool result in a hook
 

package/docs/getting-started.mdx

@@ -71,10 +71,11 @@ The root agent uses its `package.json` `name`, or its app directory name if none
 
 ### Recommended layout
 
-A minimal agent needs `instructions.md`; `agent.ts` is optional when the defaults are sufficient. Add other slots as the agent needs them:
+A minimal agent needs `instructions.md`; `agent.ts` is optional when the default config is sufficient. Framework defaults occupy ordinary agent slots, so authoring the same path replaces the default before eve compiles the agent. Add other slots as the agent needs them:
 
 ```text
 my-agent/
+├── README.md
 ├── package.json
 ├── tsconfig.json
 ├── agent/
@@ -173,13 +174,13 @@ The [Tutorial](/docs/tutorial/first-agent) builds a data analytics agent step by
 
 After the tutorial, continue with the task you need:
 
-| Goal                                                    | Read                                                                                                          |
-| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| Give the model an action it can call                    | [Tools](/docs/tools)                                                                                          |
-| Connect an MCP server or OpenAPI service                | [Connections](/docs/connections)                                                                              |
-| Reach users through Slack, Discord, or another platform | [Channels](/docs/channels/overview)                                                                           |
-| Build a browser interface                               | [Frontend Frameworks](/docs/guides/frontend/overview)                                                         |
-| Test agent behavior                                     | [Evals](/docs/evals/overview)                                                                                 |
-| Secure and deploy the agent                             | [Authentication](/docs/guides/auth-and-route-protection), then [Deployment](/docs/guides/deployment/overview) |
+| Goal                                                               | Read                                                                                                          |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| Give the model some code it can run                                | [Tools](/docs/tools)                                                                                          |
+| Connect the agent to an external MCP or OpenAPI service            | [Connections](/docs/connections)                                                                              |
+| Communicate with users through Slack, Discord, or another platform | [Channels](/docs/channels/overview)                                                                           |
+| Build a browser interface                                          | [Frontend Frameworks](/docs/guides/frontend/overview)                                                         |
+| Test agent behavior                                                | [Evals](/docs/evals/overview)                                                                                 |
+| Secure and deploy the agent                                        | [Authentication](/docs/guides/auth-and-route-protection), then [Deployment](/docs/guides/deployment/overview) |
 
 Read [Execution Model and Durability](/docs/concepts/execution-model-and-durability) for the mental model behind sessions, turns, durable steps, and parked work.

package/docs/guides/auth-and-route-protection.md

@@ -21,7 +21,7 @@ The route-auth policy lives on the HTTP channel factory (`agent/channels/eve.ts`
 
 These routes are protected by the channel's auth policy. eve fails closed by default: production traffic is rejected unless you configure an authenticator that accepts it, and anonymous access requires an explicit `none()`.
 
-`GET /eve/v1/health` is always public and skips the walk entirely, so load balancers and uptime monitors can probe it without credentials.
+The health route created by `eveChannel()` is public and skips the walk entirely, so load balancers and uptime monitors can probe it without credentials. Replacing `agent/channels/eve.ts` with a custom `defineChannel(...)` or disabling that slot also replaces or removes the health route.
 
 ```ts title="agent/channels/eve.ts"
 import { eveChannel } from "eve/channels/eve";
@@ -215,7 +215,7 @@ export default eveChannel({
 });
 ```
 
-In production, `placeholderAuth()` returns a structured `401` so a generated web chat app can say "auth isn't configured yet" instead of throwing an internal error. Replace it before a browser caller submits a production request: swap in your app's `AuthFn` or one of the shipped helpers. Delete the authored channel file entirely and eve falls back to the framework default `[vercelOidc(), localDev(), placeholderAuth()]`, which also rejects production traffic.
+In production, `placeholderAuth()` returns a structured `401` so a generated web chat app can say "auth isn't configured yet" instead of throwing an internal error. Replace it before a browser caller submits a production request: swap in your app's `AuthFn` or one of the shipped helpers. Delete the authored channel file entirely and eve selects the default channel source with `[vercelOidc(), localDev(), placeholderAuth()]`, which also rejects production traffic.
 
 You do not have to keep `vercelOidc()` in the final policy. For a self-hosted app, an app-embedded frontend, or any deployment that uses a non-Vercel identity system, use `httpBasic()`, `jwtHmac()`, `jwtEcdsa()`, generic `oidc()`, or a custom `AuthFn` that maps your verified user/session/API key into a `SessionAuthContext`.
 
@@ -243,7 +243,7 @@ When the predicate accepts a create request, `ctx.session.auth.current` and `.in
 
 > ⚠️ Both deployments must support continuation forwarding before you resume persistent remote sessions. A create-only receiver rejects a forwarded continuation with HTTP 400; the sender does not fall back to service authority. See [Forwarding the caller identity](./remote-agents#forwarding-the-caller-identity) for the upgrade behavior.
 
-Persistent sessions do not preserve caller authority between turns. Every accepted follow-up replaces `auth.current`, including replacing it with no authenticated caller on internal local delivery; per-user connection lookup is then keyed from that current principal. This prevents a later caller from resolving a prior caller's OAuth grant. It does not hide the persistent session's conversation history or artifacts from a caller who is otherwise allowed to continue that session; session ownership remains an application policy.
+Subagent sessions are persistent by default, but they do not preserve caller authority between turns. Every accepted follow-up replaces `auth.current`, including replacing it with no authenticated caller on internal local delivery; per-user connection lookup is then keyed from that current principal. This prevents a later caller from resolving a prior caller's OAuth grant. It does not hide the persistent session's conversation history or artifacts from a caller who is otherwise allowed to continue that session; session ownership remains an application policy.
 
 ## What reaches `ctx.session.auth`
 

package/docs/guides/client/output-schema.mdx

@@ -119,10 +119,10 @@ const followUp = await followUpResponse.result();
 console.log(followUp.data); // undefined unless this turn also requested a schema
 ```
 
-For task-mode output that belongs to the agent or subagent definition itself, see [`agent.ts`](../../agent-config#other-defineagent-fields) and [Subagents](../../subagents).
+For configured output that belongs to the agent or subagent definition itself, see [`agent.ts`](../../agent-config#other-defineagent-fields) and [Subagents](../../subagents).
 
 ## What to read next
 
 - [Messages](./messages): send turns with `send()`
 - [Streaming](./streaming): handle `result.completed` live
-- [`agent.ts`](../../agent-config#other-defineagent-fields): configured task-mode output
+- [`agent.ts`](../../agent-config#other-defineagent-fields): configured output for function-like invocations

package/docs/guides/client/overview.mdx

@@ -30,17 +30,19 @@ const health = await client.health();
 console.log(health.status, health.workflowId);
 ```
 
-Non-2xx responses throw `ClientError`, which carries the HTTP `status` and response `body`.
+The client requires the successful response to match `{ ok: true, status: "ready", workflowId: string }`. Non-2xx responses throw `ClientError`, which carries the HTTP `status` and response `body`; invalid JSON or a malformed successful payload throws `HealthResponseError`.
 
 ## Inspect an agent
 
-Use `info()` to inspect a development agent. The client parses and validates the complete response before returning it:
+Use `info()` to inspect an agent. The client requires the complete agent-info version 3 response before returning it:
 
 ```ts
 const info = await client.info();
 console.log(info.agent.name, info.agent.model.id);
 ```
 
+Version 3 separates active static definitions from dynamic resolvers, includes binding-backed source ownership and composition history, reports local and remote agents separately, and returns the exact compiled channel route order. A non-success response throws `ClientError`; invalid JSON, an earlier schema version, duplicate identities, inconsistent totals, or mismatched source provenance throws `AgentInfoResponseError`.
+
 ## Authentication
 
 Pass `auth` when the [eve channel](../../channels/eve) route requires credentials:

package/docs/guides/dev-tui.md

@@ -13,24 +13,35 @@ The transcript remains in your terminal scrollback after you exit. Run `/help` i
 
 ## Commands
 
-| Command       | Description                                                                                           |
-| ------------- | ----------------------------------------------------------------------------------------------------- |
-| `/model`      | Configure the model and its provider. Pass a model ID to set it directly: `/model provider/model-id`. |
-| `/add`        | Browse and install channels, MCP connections, extensions, and observability integrations.             |
-| `/deploy`     | Deploy the agent to Vercel production. Links the directory first if needed.                           |
-| `/vc:install` | Install the Vercel CLI.                                                                               |
-| `/vc:login`   | Log in to Vercel or restore access to a remote deployment.                                            |
-| `/loglevel`   | Choose which server and agent logs appear in the transcript.                                          |
-| `/traces`     | Open the local trace viewer. Pass a trace ID prefix to open a specific trace.                         |
-| `/reset`      | Start a fresh session.                                                                                |
-| `/cancel`     | Cancel the current turn without discarding settled context.                                           |
-| `/clear`      | Clear the session's model-message history. `/new` is an alias.                                        |
-| `/compact`    | Compact the current session's context.                                                                |
-| `/exit`       | Quit the UI.                                                                                          |
-| `/help`       | List available commands.                                                                              |
+| Command       | Description                                                                                                                                               |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/model`      | Configure the model and its provider. Pass a model ID to set it directly: `/model provider/model-id`.                                                     |
+| `/add`        | Browse and install channels, MCP connections, extensions, and observability integrations. Pass an item address to open it directly: `/add channel/slack`. |
+| `/deploy`     | Deploy the agent to Vercel production. Links the directory first if needed.                                                                               |
+| `/vc:install` | Install the Vercel CLI.                                                                                                                                   |
+| `/vc:login`   | Log in to Vercel or restore access to a remote deployment.                                                                                                |
+| `/loglevel`   | Choose which server and agent logs appear in the transcript.                                                                                              |
+| `/traces`     | Open the local trace viewer. Pass a trace ID prefix to open a specific trace.                                                                             |
+| `/reset`      | Start a fresh session.                                                                                                                                    |
+| `/cancel`     | Cancel the current turn without discarding settled context.                                                                                               |
+| `/clear`      | Clear the session's model-message history. `/new` is an alias.                                                                                            |
+| `/compact`    | Compact the current session's context.                                                                                                                    |
+| `/exit`       | Quit the UI.                                                                                                                                              |
+| `/help`       | List available commands.                                                                                                                                  |
 
 `/model`, `/add`, `/deploy`, and `/traces` are available when `eve dev` runs locally. They are unavailable when the UI connects to a server with `--url`.
 
+## Add an integration
+
+Bare `/add` opens the categorized registry browser. Pass an item address — `<category>/<name>`, where category is `channel`, `connection`, `extension`, or `instrumentation` — to skip the category and search screens and open that item directly:
+
+```text
+/add channel/slack
+/add extension/agent-browser
+```
+
+Either way the UI shows the item's details and asks to confirm before installing, then runs the same installation and setup prompts. Choosing **Back** on a directly addressed item returns to the registry browser.
+
 ## Work with the agent
 
 Type a message and press `Enter` to send it. When the agent asks a question or requests tool approval, respond in the prompt shown by the UI. Connection authorization can open a browser; keep local `eve dev` running until the browser returns to it.

package/docs/guides/frontend/nuxt.mdx

@@ -41,12 +41,13 @@ The `eve` key accepts only two options, `eveRoot` and `eveBuildCommand`.
 const { status, send } = useEveAgent();
 
 const isBusy = computed(() => status.value === "submitted" || status.value === "streaming");
+const isInputDisabled = computed(() => isBusy.value || status.value === "resuming");
 
 const message = ref("");
 
 async function handleSubmit() {
   const text = message.value.trim();
-  if (!text || isBusy.value) return;
+  if (!text || isInputDisabled.value) return;
   message.value = "";
   await send(text);
 }
@@ -54,8 +55,8 @@ async function handleSubmit() {
 
 <template>
   <form @submit.prevent="handleSubmit">
-    <input v-model="message" :disabled="isBusy" />
-    <button type="submit" :disabled="isBusy">Send</button>
+    <input v-model="message" :disabled="isInputDisabled" />
+    <button type="submit" :disabled="isInputDisabled">Send</button>
   </form>
 </template>
 ```

package/docs/guides/frontend/overview.mdx

@@ -36,6 +36,7 @@ import { useEveAgent } from "eve/react";
 export function Chat() {
   const agent = useEveAgent();
   const isBusy = agent.status === "submitted" || agent.status === "streaming";
+  const isResuming = agent.status === "resuming";
 
   return (
     <form
@@ -43,7 +44,7 @@ export function Chat() {
         event.preventDefault();
         const form = new FormData(event.currentTarget);
         const message = String(form.get("message") ?? "").trim();
-        if (message.length > 0) {
+        if (message.length > 0 && !isResuming) {
           void agent.send(message, isBusy ? { turnPolicy: "steer" } : undefined);
         }
       }}
@@ -56,8 +57,10 @@ export function Chat() {
           )}
         </article>
       ))}
-      <input name="message" />
-      <button type="submit">Send</button>
+      <input disabled={isResuming} name="message" />
+      <button disabled={isResuming} type="submit">
+        Send
+      </button>
     </form>
   );
 }
@@ -67,18 +70,18 @@ export function Chat() {
 
 `useEveAgent()` returns the current UI state plus commands:
 
-| Field     | What it is                                                                  |
-| --------- | --------------------------------------------------------------------------- |
-| `data`    | Projected UI state from the reducer. Defaults to `{ messages }`.            |
-| `status`  | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`. Drives the composer. |
-| `error`   | The last `Error` thrown, if any.                                            |
-| `events`  | Raw eve stream events for this session.                                     |
-| `session` | Serializable fixed session cursor (`sessionId`, `streamIndex`).             |
-| `send`    | Send text or a multi-part message, with per-turn options.                   |
-| `respond` | Answer pending HITL input requests, with per-turn options.                  |
-| `resume`  | Replay an attached session and follow its in-flight turn.                   |
-| `cancel`  | Request durable cancellation of the active turn.                            |
-| `reset`   | Clear local events, data, errors, and the local session cursor.             |
+| Field     | What it is                                                                                |
+| --------- | ----------------------------------------------------------------------------------------- |
+| `data`    | Projected UI state from the reducer. Defaults to `{ messages }`.                          |
+| `status`  | `"ready"`, `"resuming"`, `"submitted"`, `"streaming"`, or `"error"`. Drives the composer. |
+| `error`   | The last `Error` thrown, if any.                                                          |
+| `events`  | Raw eve stream events for this session.                                                   |
+| `session` | Serializable fixed session cursor (`sessionId`, `streamIndex`).                           |
+| `send`    | Send text or a multi-part message, with per-turn options.                                 |
+| `respond` | Answer pending HITL input requests, with per-turn options.                                |
+| `resume`  | Replay an attached session and follow its in-flight turn.                                 |
+| `cancel`  | Request durable cancellation of the active turn.                                          |
+| `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 need the authoritative wire events directly, for example to persist an audit log or build a custom projection.
 
@@ -104,7 +107,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. To replace an active turn with a follow-up, send the message with `turnPolicy: "steer"`. eve accepts the message through the durable session, cancels the active turn, and keeps the hook attached through the replacement turn:
+Assistant text, reasoning, tool calls, and tool results stream into `data` as they arrive, and a new turn moves `status` from `ready` to `submitted` to `streaming` and back. Resuming an attached session uses `resuming` while eve performs bounded catch-up. Disable message and HITL submission in that state. A settled tail moves directly to `ready`; an in-flight tail moves to `streaming` before eve follows it. To replace an active turn with a follow-up, send the message with `turnPolicy: "steer"`. eve accepts the message through the durable session, cancels the active turn, and keeps the hook attached through the replacement turn:
 
 ```tsx
 await agent.send(message, { turnPolicy: "steer" });
@@ -299,11 +302,11 @@ render historical messages without replaying the whole stream. A database-backed
 chat app should usually persist stream events as they arrive with `onEvent` and
 then save a final snapshot in `onFinish`.
 
-`initialEvents` must be an ordered prefix of the same session's stream, but its endpoint does not have to line up exactly with where the stream resumes. Every event carries a stable [`meta.id`](/docs/concepts/sessions-runs-and-streaming#the-event-envelope), and the store drops any event whose id it has already applied — so a saved log that overlaps the replayed prefix renders once, and `onEvent` only fires for events your UI has not seen.
+`initialEvents` must be an ordered prefix of the same session's stream, but its endpoint does not have to line up exactly with where the stream resumes. When the event count matches `initialSession.streamIndex`, catch-up continues from that cursor. A partial or overlapping saved log falls back to index `0`. Every event carries a stable [`meta.id`](/docs/concepts/sessions-runs-and-streaming#the-event-envelope), and the store drops any event whose id it has already applied, so an overlapping replay renders once and `onEvent` only fires for events your UI has not seen.
 
 For multiple chat threads, keep one saved event log and session cursor per thread. `agent`, `host`, `reducer`, `session`, `initialEvents`, `initialSession`, `auth`, `headers`, `optimistic`, and `resume` are read when the hook creates its store, so remount the chat component when switching threads, for example with `key={chat.id}`.
 
-Pass `resume: true` with `initialSession` to rebuild the projection from the durable stream after mount. If the stream ends at an in-flight turn, the binding stays attached until that turn reaches its boundary. If the stream already ends at a settled session boundary, replay stops at the history tail.
+Pass `resume: true` with `initialSession` to rebuild the projection from the durable stream after mount. While `status` is `"resuming"`, render hydrated `data` but disable message and HITL submission; do not present cancellation or active-turn progress controls. If catch-up finds an in-flight turn, `status` changes to `"streaming"` before the binding follows it to a boundary. A settled tail changes directly to `"ready"`, and a terminal session failure changes to `"error"`.
 
 ```tsx
 const agent = useEveAgent({

package/docs/guides/frontend/sveltekit.mdx

@@ -51,10 +51,11 @@ With the plugin in `vite.config.ts`, components call [`useEveAgent`](./use-eve-a
   const agent = useEveAgent();
   let message = $state("");
   let isBusy = $derived(agent.status === "submitted" || agent.status === "streaming");
+  let isInputDisabled = $derived(isBusy || agent.status === "resuming");
 
   async function handleSubmit() {
     const text = message.trim();
-    if (!text || isBusy) return;
+    if (!text || isInputDisabled) return;
     message = "";
     await agent.send(text);
   }
@@ -64,8 +65,8 @@ With the plugin in `vite.config.ts`, components call [`useEveAgent`](./use-eve-a
   event.preventDefault();
   void handleSubmit();
 }}>
-  <input bind:value={message} disabled={isBusy} />
-  <button type="submit" disabled={isBusy}>Send</button>
+  <input bind:value={message} disabled={isInputDisabled} />
+  <button type="submit" disabled={isInputDisabled}>Send</button>
 </form>
 ```
 

package/docs/guides/frontend/use-eve-agent-svelte.mdx

@@ -18,10 +18,11 @@ Call the binding once for a conversation and read its reactive getters directly.
   const agent = useEveAgent();
   let message = $state("");
   let isBusy = $derived(agent.status === "submitted" || agent.status === "streaming");
+  let isInputDisabled = $derived(isBusy || agent.status === "resuming");
 
   async function handleSubmit() {
     const text = message.trim();
-    if (!text || isBusy) return;
+    if (!text || isInputDisabled) return;
     message = "";
     await agent.send(text);
   }
@@ -35,8 +36,8 @@ Call the binding once for a conversation and read its reactive getters directly.
   event.preventDefault();
   void handleSubmit();
 }}>
-  <input bind:value={message} disabled={isBusy} />
-  <button type="submit" disabled={isBusy}>Send</button>
+  <input bind:value={message} disabled={isInputDisabled} />
+  <button type="submit" disabled={isInputDisabled}>Send</button>
 </form>
 ```
 
@@ -106,7 +107,7 @@ See [Human-in-the-loop prompts](./overview#human-in-the-loop-prompts) for reques
 
 ## Cancel, reset, and resume
 
-Call `agent.cancel()` to stop the durable server-side turn while the binding remains attached through settlement. Destroying the component only disconnects its local stream; it does not cancel server execution. Call `agent.reset()` to clear local state and start a new session. Pass `initialSession`, `initialEvents`, and `resume: true` to restore a saved conversation and follow an in-flight turn. Use `agent.resume()` directly when restoration is controlled imperatively. See [Resumable sessions](./overview#resumable-sessions) for the persistence contract and [Sending and streaming](./overview#sending-and-streaming) for cancellation behavior.
+Call `agent.cancel()` to stop the durable server-side turn while the binding remains attached through settlement. Destroying the component only disconnects its local stream; it does not cancel server execution. Call `agent.reset()` to clear local state and start a new session. Pass `initialSession`, `initialEvents`, and `resume: true` to restore a saved conversation and follow an in-flight turn. During bounded catch-up, `agent.status` is `"resuming"`; keep the hydrated conversation visible, disable submission, and wait for `"ready"`, `"error"`, or `"streaming"`. Use `agent.resume()` directly when restoration is controlled imperatively. See [Resumable sessions](./overview#resumable-sessions) for the persistence contract and [Sending and streaming](./overview#sending-and-streaming) for cancellation behavior.
 
 ## Custom host and credentials
 

package/docs/guides/frontend/use-eve-agent-vue.mdx

@@ -19,10 +19,11 @@ import { computed, ref } from "vue";
 const { data, status, send } = useEveAgent();
 const message = ref("");
 const isBusy = computed(() => status.value === "submitted" || status.value === "streaming");
+const isInputDisabled = computed(() => isBusy.value || status.value === "resuming");
 
 async function handleSubmit() {
   const text = message.value.trim();
-  if (!text || isBusy.value) return;
+  if (!text || isInputDisabled.value) return;
   message.value = "";
   await send(text);
 }
@@ -33,8 +34,8 @@ async function handleSubmit() {
     <p>{{ item.role }}: {{ item.parts }}</p>
   </div>
   <form @submit.prevent="handleSubmit">
-    <input v-model="message" :disabled="isBusy" />
-    <button type="submit" :disabled="isBusy">Send</button>
+    <input v-model="message" :disabled="isInputDisabled" />
+    <button type="submit" :disabled="isInputDisabled">Send</button>
   </form>
 </template>
 ```
@@ -108,7 +109,7 @@ See [Human-in-the-loop prompts](./overview#human-in-the-loop-prompts) for reques
 
 ## Cancel, reset, and resume
 
-Call `cancel()` to stop the durable server-side turn while the composable remains attached through settlement. Disposing the component only disconnects its local stream; it does not cancel server execution. Call `reset()` to clear local state and start a new session. Pass `initialSession`, `initialEvents`, and `resume: true` to restore a saved conversation and follow an in-flight turn. Use `resume()` directly when restoration is controlled imperatively. See [Resumable sessions](./overview#resumable-sessions) for the persistence contract and [Sending and streaming](./overview#sending-and-streaming) for cancellation behavior.
+Call `cancel()` to stop the durable server-side turn while the composable remains attached through settlement. Disposing the component only disconnects its local stream; it does not cancel server execution. Call `reset()` to clear local state and start a new session. Pass `initialSession`, `initialEvents`, and `resume: true` to restore a saved conversation and follow an in-flight turn. During bounded catch-up, `status.value` is `"resuming"`; keep the hydrated conversation visible, disable submission, and wait for `"ready"`, `"error"`, or `"streaming"`. Use `resume()` directly when restoration is controlled imperatively. See [Resumable sessions](./overview#resumable-sessions) for the persistence contract and [Sending and streaming](./overview#sending-and-streaming) for cancellation behavior.
 
 ## Custom host and credentials
 

package/docs/guides/instrumentation.md

@@ -164,6 +164,7 @@ Structural tags describe each run's place in the tree:
 - `$eve.subagent`: compiled graph node id (subagent runs only)
 - `$eve.trigger`: the channel kind that started the run
 - `$eve.title`: truncated title derived from the first user message
+- `$eve.trace_id`: trace id of the sampled agent trace containing the run, written on session, subagent, and turn rows so a dashboard run can be joined to its OpenTelemetry trace. Present only when the trace is sampled; absence means no exported OTEL trace exists.
 
 Per-turn usage tags are written on each step of a turn, accumulating cumulative totals (last write wins):