eve 0.44.4 → 0.45.0

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,7 +71,7 @@ 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/
@@ -174,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/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):
 

package/docs/guides/remote-agents.md

@@ -20,15 +20,15 @@ export default defineRemoteAgent({
 
 `defineRemoteAgent` accepts:
 
-| Parameter          | Type                                          | Required | Default           | Description                                                                                                                                                                          |
-| ------------------ | --------------------------------------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `url`              | `string \| (() => string \| Promise<string>)` | Yes      | n/a               | Base URL of the remote eve deployment to call. A string is baked at compile time; a function is resolved at runtime (see [Runtime URLs](#runtime-urls)).                             |
-| `description`      | `string`                                      | Yes      | n/a               | Model-visible delegation description.                                                                                                                                                |
-| `auth`             | `OutboundAuthFn`                              | No       | none              | Outbound auth hook from `eve/agents/auth`.                                                                                                                                           |
-| `forwardPrincipal` | `boolean`                                     | No       | `false`           | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)).                                   |
-| `headers`          | `HeadersValue`                                | No       | none              | Static or lazily resolved request headers.                                                                                                                                           |
-| `path`             | `string`                                      | No       | `/eve/v1/session` | Route appended to `url` for the create-session request.                                                                                                                              |
-| `outputSchema`     | `StandardSchema \| JSON Schema`               | No       | none              | Structured return type the caller requires. Enforced by the remote agent like any task-mode output schema. Set it on the definition to apply to every call, or override it per call. |
+| Parameter          | Type                                          | Required | Default           | Description                                                                                                                                              |
+| ------------------ | --------------------------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`              | `string \| (() => string \| Promise<string>)` | Yes      | n/a               | Base URL of the remote eve deployment to call. A string is baked at compile time; a function is resolved at runtime (see [Runtime URLs](#runtime-urls)). |
+| `description`      | `string`                                      | Yes      | n/a               | Model-visible delegation description.                                                                                                                    |
+| `auth`             | `OutboundAuthFn`                              | No       | none              | Outbound auth hook from `eve/agents/auth`.                                                                                                               |
+| `forwardPrincipal` | `boolean`                                     | No       | `false`           | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)).       |
+| `headers`          | `HeadersValue`                                | No       | none              | Static or lazily resolved request headers.                                                                                                               |
+| `path`             | `string`                                      | No       | `/eve/v1/session` | Route appended to `url` for the create-session request.                                                                                                  |
+| `outputSchema`     | `StandardSchema \| JSON Schema`               | No       | none              | Structured return type for the first turn of each fresh remote session. A continuation may provide its own per-call schema.                              |
 
 ## Dynamic remote agents
 
@@ -82,19 +82,36 @@ The function may be async and must return a non-empty string. `auth` and `header
 
 To the model, a remote agent is another subagent tool. You call it the same way you call a local subagent, with a `message` and an optional `outputSchema`. The message must carry the full task, including any context the remote agent needs, because it never receives the parent's conversation history.
 
-To get one structured result back instead of an open-ended reply, set an `outputSchema` on the agent definition or on an individual call. The remote agent then runs in task mode, a single-shot delegation that returns structured output as the tool result. See [Subagents](../subagents) for how task mode works.
+To require structured output, set an `outputSchema` on the agent definition for fresh delegations or on an individual call for that turn. The structured value becomes the tool result, and the remote child remains available for follow-up messages. See [Subagents](../subagents) for continuation behavior.
 
 ## Outbound auth
 
-`auth` is an `OutboundAuthFn` from `eve/agents/auth` that attaches request headers to the outbound dispatch:
+Use `vercelOidc()` from `eve/agents/auth` when one Vercel-deployed eve agent calls another, as shown in the first example on this page.
+
+For calls between different Vercel projects, allow the calling project on the receiving agent's eve channel:
+
+```ts title="agent/channels/eve.ts"
+import { vercelOidc, vercelSubject } from "eve/channels/auth";
+import { eveChannel } from "eve/channels/eve";
+
+export default eveChannel({
+  auth: [
+    vercelOidc({
+      subjects: [
+        vercelSubject({
+          teamSlug: "acme",
+          projectName: "calling-agent",
+          environment: "production",
+        }),
+      ],
+    }),
+  ],
+});
+```
 
-| Helper                          | Header                                                                       |
-| ------------------------------- | ---------------------------------------------------------------------------- |
-| `vercelOidc(opts?)`             | `Authorization: Bearer <Vercel OIDC token>` (deployment-to-deployment trust) |
-| `bearer(token)`                 | `Authorization: Bearer <token>` (static or lazily resolved)                  |
-| `basic({ username, password })` | `Authorization: Basic …`                                                     |
+Set `teamSlug`, `projectName`, and `environment` to the calling deployment's Vercel OIDC subject. See [subject patterns and `vercelSubject(...)`](./auth-and-route-protection#subjects-patterns-and-vercelsubject) for other environments and wildcard matching.
 
-If you are calling another Vercel-deployed eve agent, reach for `vercelOidc()`. The remote verifies the OIDC token to authorize the caller. See [Auth & route protection](./auth-and-route-protection) for the receiving side.
+If [Vercel Deployment Protection](https://vercel.com/docs/deployment-protection) is active on the receiving project, also configure [Trusted Sources](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/trusted-sources) to allow the calling project and environment. The eve subject allowlist and Trusted Sources are separate checks; cross-project calls need both.
 
 ## Forwarding the caller identity
 
@@ -130,7 +147,7 @@ A receiver on an eve version that predates all principal forwarding may instead
 
 A local subagent runs inline. A remote one runs in its own deployment, so dispatch is asynchronous:
 
-1. The parent starts a task-mode session on the remote's `POST /eve/v1/session`, passing a framework callback URL.
+1. The parent starts a persistent conversation session on the remote's `POST /eve/v1/session`, passing a framework callback URL.
 2. The parent turn parks (suspends durably without holding compute; see [Execution model & durability](../concepts/execution-model-and-durability)) until the remote posts a terminal callback.
 3. When the callback arrives, the parent resumes and surfaces the result.
 
@@ -138,6 +155,8 @@ The parent stream carries the same `subagent.called`, `action.result`, and `suba
 
 Cancelling the parent while a remote call is active sends an authenticated `POST /eve/v1/session/:childSessionId/cancel` to the remote and waits for that request to be accepted before the parent settles. eve resolves the remote's `headers` and `auth` again for every cancellation attempt, so rotating credentials work the same way as they do for session creation. Cancellation always uses the standard eve cancel path on `url`, even when `path` customizes only the create-session endpoint. The remote child reports `turn.cancelled` → `session.waiting` on its own stream; an older or unreachable remote is logged but cannot turn the parent's cancellation into a failure.
 
+When the parent session ends, eve sends an authenticated `POST /eve/v1/session/:childSessionId/reset` for each remote child. Reset retires the parked remote session and recursively cleans up its descendants. The request uses freshly resolved `headers` and `auth`; failures are logged so an unreachable remote cannot block parent finalization.
+
 Both failure paths surface to the parent as a failed tool result, so the caller can explain or recover within the same session. A failed _start_ returns the error inline. A remote that starts and then fails posts a terminal failure callback, which the parent receives as an errored subagent result carrying the remote's error (or `REMOTE_AGENT_FAILED` when none is supplied). Terminal callback delivery runs as a durable step on the underlying workflow engine (see [Execution model & durability](../concepts/execution-model-and-durability)). A failed callback POST is rethrown rather than marking the task complete, so the engine retries it.
 
 ## What to read next

package/docs/patterns/multi-tenant-approvals.md

@@ -21,7 +21,7 @@ Tenant policy storage remains yours. It might be a few columns in PostgreSQL, a
 The current caller and initiating caller are both available on the session. This example requires them to belong to the same tenant before consulting policy:
 
 ```ts title="agent/lib/tenant-approval.ts"
-import type { ApprovalContext, ApprovalStatus } from "eve/tools";
+import type { ApprovalContext, ApprovalStatus } from "eve/tools/approval";
 import { approvalPolicies } from "./approval-policies";
 
 type Surface = "connection" | "tool";

package/docs/reference/cli.md

@@ -296,11 +296,9 @@ Reads the immutable OTLP/JSON segments under `.eve/traces/v1`, so `eve dev` need
 
 Span rows carry inline metrics when the span recorded them — `↑input`/`↓output` token counts, gateway cost, and the tool name for `ai.toolCall` spans — and the header aggregates models, token totals, cost, and error count across the trace's step spans. `--verbose` expands each span under its tree row: status (with the error message on failures), timing, ids, every attribute (prompts, responses, and tool payloads as transcripts or pretty-printed JSON), and every span event with its offset from span start. `--json` prints the same records as JSON, one object per selected trace.
 
-A subagent keeps its own session id but records into the trace its parent had open at dispatch, so delegated work appears under the session that caused it, tagged with `agent.root.session.id`. Either session id resolves to that trace. A remote agent traces under its own deployment and is not recorded here.
+A local subagent keeps its own session id but records into the parent trace. Its turn is parented to the `agent.action` span that dispatched it, so the span tree carries the relationship without duplicate lineage attributes; `agent.subagent.name` remains on the child turn as a standalone label. Either session id resolves to that trace. Remote agents propagate the parent trace context over `traceparent`.
 
-A session long enough to outgrow one trace — far longer than anything you will drive locally — continues into a new one. Each is a session window, numbered from zero on `agent.session.window`; passing a session id shows every window it produced, oldest first, and a trace id shows just that window.
-
-One parent turn can dispatch several subagents into the same window, so a child's turn spans name the dispatch: `agent.parent.session.id`, `agent.parent.turn.id`, and `agent.parent.call_id` identify the tool call that created the child, and `agent.subagent.name` the subagent it invoked. Top-level sessions carry none of these.
+A durable session keeps one persisted trace context across turns and worker resumptions. Independently replayed attempts can still produce another trace; passing the session id shows every trace it produced, oldest first.
 
 Every span carries a real duration except `agent.session`: an idle session never closes, so it is recorded as a zero-duration marker and the span tree shows its descendant extent instead. A turn's span is written when the turn settles, so a running turn shows only its steps.
 

package/docs/reference/typescript-api.md

@@ -3,7 +3,7 @@ title: "TypeScript API Reference"
 description: "The define* helpers, the runtime ctx, and where each one is imported from."
 ---
 
-This is the public surface of the `eve` package: the `define*` helpers you author with, the `ctx` they receive at runtime, and the import path for each. The full contract lives in `packages/eve/src/public/index.ts`; anything not exported there is a framework internal.
+This is the public surface of the `eve` package: the `define*` helpers you author with, the `ctx` they receive at runtime, and the import path for each. The package's export map defines the full contract; source files that are not reachable through an exported package subpath are framework internals.
 
 Identity comes from the filesystem, not a field you set. A tool at `agent/tools/get_weather.ts` is `get_weather`, and a connection at `agent/connections/linear.ts` is `linear`, so no definition carries a `name` or `id`.
 
@@ -52,7 +52,9 @@ export default defineTool({
 | `mockModel`                                           | `eve/evals`                                          | Deterministic fixture agent models                                         | [Evals](../evals/overview)                             |
 | `useEveAgent`                                         | `eve/react`, `eve/vue`, `eve/svelte`                 | frontend                                                                   | [Frontend](../guides/frontend/overview)                |
 
-A few additional helpers round out the set: `defineGlobTool`, `defineGrepTool`, `disableTool`, `experimental_workflow`, and `webSearch` from `eve/tools` (see [Built-in tools](../concepts/built-in-tools)), `sleep` from `eve/tools/sleep`, the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval policies `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a framework-provided tool, import its definition from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `todo`, `loadSkill`). `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `ExperimentalWorkflowToolInput`, `WebSearchToolInput`, and `WebSearchProvider` are exported from `eve/tools` for their corresponding tool configuration helpers.
+Tool-wide authoring helpers such as `defineTool`, `defineDynamic`, and `disableTool` come from `eve/tools`. Capability-specific definitions and helpers use their own subpaths (see [Built-in tools](../concepts/built-in-tools)): reusable definitions such as `bash` and `glob` come from `eve/tools/<name>`, `webSearch` comes from `eve/tools/web_search`, `experimental_workflow` comes from `eve/tools/workflow`, `sleep` comes from `eve/tools/sleep`, and approval policies and types come from `eve/tools/approval`. The route verbs `GET`/`HEAD`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`/`WS` plus `disableRoute` come from `eve/channels`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` come from `eve/channels/auth`.
+
+`AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `ExperimentalWorkflowToolInput` is exported from `eve/tools/workflow`; `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.
 
 `defineInstructions` accepts `{ content: string, role?: "system" | "user" }`; omitted `role` means `"system"`. Its `eve/instructions` version of `defineDynamic` accepts only `session.started` and `turn.started` handlers returning `defineInstructions(...)` or `null`. The legacy `{ markdown: string }` definition remains available as a deprecated system-role form.
 
@@ -70,35 +72,37 @@ A few additional helpers round out the set: `defineGlobTool`, `defineGrepTool`,
 
 ## Imports at a glance
 
-| Import                                                      | Holds                                                                                                     |
-| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `eve`                                                       | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types                                   |
-| `eve/tools`                                                 | `defineTool`, `defineDynamic`, `defineGlobTool`, `defineGrepTool`, `disableTool`, `experimental_workflow` |
-| `eve/tools/defaults`                                        | framework tool definitions as plain values                                                                |
-| `eve/tools/approval`                                        | `always`, `once`, `never`                                                                                 |
-| `eve/tools/sleep`                                           | opt-in durable `sleep` tool                                                                               |
-| `eve/connections`                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`                                                    |
-| `eve/channels`                                              | `defineChannel`, route verbs                                                                              |
-| `eve/channels/eve`                                          | `eveChannel`                                                                                              |
-| `eve/channels/auth`                                         | `localDev`, `vercelOidc`, `placeholderAuth`                                                               |
-| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories                                                                                |
-| `eve/hooks`                                                 | `defineHook`                                                                                              |
-| `eve/schedules`                                             | `defineSchedule`                                                                                          |
-| `eve/skills`                                                | `defineSkill`, `defineDynamic`                                                                            |
-| `eve/instructions`                                          | `defineInstructions`, `defineDynamic`                                                                     |
-| `eve/context`                                               | `defineState`, session and state types                                                                    |
-| `eve/sandbox`                                               | `defineSandbox`, backends                                                                                 |
-| `eve/instrumentation`                                       | `defineInstrumentation`, `isChannel`                                                                      |
-| `eve/models/openai`                                         | `chatgpt`, deprecated `experimental_chatgpt`                                                              |
-| `eve/evals`                                                 | `defineEval`, `defineEvalConfig`, `mockModel`, eval types                                                 |
-| `eve/evals/expect`                                          | `includes`, `equals`, `matches`, `similarity`                                                             |
-| `eve/evals/reporters`                                       | `Braintrust`, `JUnit`, `EvalReporter`                                                                     |
-| `eve/evals/loaders`                                         | `loadJson`, `loadYaml`                                                                                    |
-| `eve/react`, `eve/vue`, `eve/svelte`                        | `useEveAgent`                                                                                             |
-| `eve/next`, `eve/nuxt`, `eve/sveltekit`                     | framework bundler plugins                                                                                 |
-| [`eve/client`](../guides/client/overview)                   | `Client`, `ClientSession`                                                                                 |
-
-Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). For the exhaustive list, read `packages/eve/src/public/index.ts`.
+| Import                                                                      | Holds                                                                     |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `eve`                                                                       | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types   |
+| `eve/tools`                                                                 | `defineTool`, `defineDynamic`, `disableTool`, generic tool types          |
+| `eve/tools/{bash,read_file,write_file,todo,web_fetch,load_skill,glob,grep}` | Individual reusable tool definitions                                      |
+| `eve/tools/approval`                                                        | Approval types and `always`, `once`, `never`                              |
+| `eve/tools/web_search`                                                      | Provider-managed `webSearch` configuration                                |
+| `eve/tools/workflow`                                                        | Experimental `Workflow` tool definition                                   |
+| `eve/tools/sleep`                                                           | Opt-in durable `sleep` tool                                               |
+| `eve/connections`                                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`                    |
+| `eve/channels`                                                              | `defineChannel`, `disableRoute`, route verbs                              |
+| `eve/channels/eve`                                                          | `eveChannel`                                                              |
+| `eve/channels/auth`                                                         | `localDev`, `vercelOidc`, `placeholderAuth`                               |
+| `eve/channels/{slack,discord,teams,telegram,twilio,github}`                 | platform channel factories                                                |
+| `eve/hooks`                                                                 | `defineHook`                                                              |
+| `eve/schedules`                                                             | `defineSchedule`                                                          |
+| `eve/skills`                                                                | `defineSkill`, `defineDynamic`                                            |
+| `eve/instructions`                                                          | `defineInstructions`, `defineDynamic`                                     |
+| `eve/context`                                                               | `defineState`, session and state types                                    |
+| `eve/sandbox`                                                               | `defineSandbox`, backends                                                 |
+| `eve/instrumentation`                                                       | `defineInstrumentation`, `isChannel`                                      |
+| `eve/models/openai`                                                         | `chatgpt`, deprecated `experimental_chatgpt`                              |
+| `eve/evals`                                                                 | `defineEval`, `defineEvalConfig`, `mockModel`, eval types                 |
+| `eve/evals/expect`                                                          | `includes`, `equals`, `matches`, `similarity`                             |
+| `eve/evals/reporters`                                                       | `Braintrust`, `JUnit`, `EvalReporter`                                     |
+| `eve/evals/loaders`                                                         | `loadJson`, `loadYaml`                                                    |
+| `eve/react`, `eve/vue`, `eve/svelte`                                        | `useEveAgent`                                                             |
+| `eve/next`, `eve/nuxt`, `eve/sveltekit`                                     | framework bundler plugins                                                 |
+| [`eve/client`](../guides/client/overview)                                   | `Client`, `ClientSession`, health and agent-info schemas, response errors |
+
+Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). The `exports` field in `packages/eve/package.json` lists every public entrypoint.
 
 ## ChatGPT subscription models
 

package/docs/sandbox.mdx

@@ -5,7 +5,7 @@ description: "The agent's isolated bash environment, including built-in file too
 
 The sandbox is the agent's isolated bash environment: a filesystem rooted at `/workspace` where it can run shell commands, execute scripts, and read or write files without ever touching your app runtime. Every eve agent has exactly one. The default `bash`, `read_file`, and `write_file` tools target it; you can also add the framework's `glob` and `grep` tools or access it from authored code.
 
-A working sandbox exists by default, with nothing to author. Override it only to add setup, seed files, pick a backend, or lock down the network.
+A working sandbox exists by default, with nothing to author. eve selects a framework-provided `defineSandbox({})` source for each local agent; `agent/sandbox.ts` or `agent/sandbox/sandbox.ts` replaces that source. Override it only to add setup, seed files, pick a backend, or lock down the network.
 
 The default sandbox is not a substitute for configuring network policy, credentials, retention, deletion, or other controls your application requires.