eve 0.10.0 → 0.11.0

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

@@ -3,7 +3,7 @@ title: "useEveAgent (Svelte)"
 description: "Svelte 5 binding that drives an Eve agent session from the browser."
 ---
 
-`useEveAgent()` from `eve/svelte` is the browser side of an Eve session in a Svelte 5 app. Call it once and you get a long-lived session you can send turns to, with every stream event projected into rune-friendly reactive data. On SvelteKit, the [Vite plugin](./sveltekit) wires up the routes. The [frontend overview](./overview) covers the model shared across frameworks.
+`useEveAgent()` from `eve/svelte` is the browser side of an Eve session in a Svelte 5 app. Call it once for a long-lived session you can send turns to, with every stream event projected into rune-friendly reactive data. On SvelteKit, the [Vite plugin](./sveltekit) wires up the routes. The [frontend overview](./overview) covers the model shared across frameworks.
 
 ## Basic usage
 
@@ -23,16 +23,16 @@ Import from `eve/svelte` and read the reactive getters directly. No `$` prefix:
 
 ## What it returns
 
-| Property  | Type                 | Description                                                               |
-| --------- | -------------------- | ------------------------------------------------------------------------- |
-| `data`    | `TData`              | Projected state. With the default reducer, `EveMessageData` (`messages`). |
-| `status`  | `UseEveAgentStatus`  | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
-| `error`   | `Error \| undefined` | Last transport-level error.                                               |
-| `events`  | `readonly ...[]`     | Raw server events for this session.                                       |
-| `session` | `SessionState`       | Snapshot of session state.                                                |
-| `send`    | `(input) => Promise` | Send text or a full turn (multi-part, attachments, HITL responses).       |
-| `stop`    | `() => void`         | Abort the in-flight request.                                              |
-| `reset`   | `() => void`         | Clear state and start a new session.                                      |
+| Property  | Type                                        | Description                                                               |
+| --------- | ------------------------------------------- | ------------------------------------------------------------------------- |
+| `data`    | `TData`                                     | Projected state. With the default reducer, `EveMessageData` (`messages`). |
+| `status`  | `UseEveAgentStatus`                         | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
+| `error`   | `Error \| undefined`                        | Last transport-level error.                                               |
+| `events`  | `readonly HandleMessageStreamEvent[]`       | Raw server events for this session.                                       |
+| `session` | `SessionState`                              | Snapshot of session state.                                                |
+| `send`    | `(input: SendTurnPayload) => Promise<void>` | Send text or a full turn (multi-part, attachments, HITL responses).       |
+| `stop`    | `() => void`                                | Abort the in-flight request.                                              |
+| `reset`   | `() => void`                                | Clear state and start a new session.                                      |
 
 These state fields are reactive getters, so read them straight from templates, `$derived`, or `$effect`. They are not stores, so don't prefix them with `$`.
 
@@ -62,20 +62,44 @@ These state fields are reactive getters, so read them straight from templates, `
 </form>
 ```
 
-When a turn is more than plain text, reach for `send()`. Attachments follow the AI SDK `UserContent` format:
+When a turn is more than plain text, reach for `send()`. Attachments follow the AI SDK `UserContent` format. Send file data as a base64 `data:` URL so it survives the JSON transport:
 
 ```ts
+const bytes = new Uint8Array(await file.arrayBuffer());
+const base64 = btoa(String.fromCodePoint(...bytes));
+
 await agent.send({
   message: [
     { type: "text", text: "Describe this image." },
-    { type: "file", data: fileBytes, mediaType: "image/png" },
+    { type: "file", data: `data:${file.type};base64,${base64}`, mediaType: file.type },
   ],
 });
 ```
 
 ## Human-in-the-loop prompts
 
-A tool opts into approval with `needsApproval` ([Tools](../../tools)). When one fires, the pending request rides along on a `dynamic-tool` part of the latest message. Read it, then answer with `agent.send({ inputResponses })`. This find-and-answer flow is identical across frameworks, so the full example lives in the [Frontend overview](./overview#human-in-the-loop-prompts).
+A tool opts into approval with `needsApproval` ([Tools](../../tools)). When one fires, the pending request rides along on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `agent.send({ inputResponses })`:
+
+```ts
+import type { EveDynamicToolPart, EveMessagePart } from "eve/svelte";
+
+const isDynamicToolPart = (part: EveMessagePart): part is EveDynamicToolPart =>
+  part.type === "dynamic-tool";
+
+const request = agent.data.messages
+  .at(-1)
+  ?.parts.filter(isDynamicToolPart)
+  .map((part) => part.toolMetadata?.eve?.inputRequest)
+  .find((value) => value !== undefined);
+
+if (request) {
+  await agent.send({
+    inputResponses: [{ requestId: request.requestId, optionId: "approve" }],
+  });
+}
+```
+
+The find-and-answer flow is identical across frameworks. The [React hook reference](./overview) covers the longer walkthrough.
 
 ## Stop, reset, and resume
 
@@ -104,6 +128,74 @@ const agent = useEveAgent({
 });
 ```
 
+## Attach page context per turn
+
+`clientContext` adds ephemeral context for the next model call and nothing more. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, never dispatches a turn on its own, and never lands in durable session history. Pass it to `send()`:
+
+```ts
+await agent.send({
+  message: "What should I do on this screen?",
+  clientContext: { route: "/billing", plan: "pro", seatsUsed: 4 },
+});
+```
+
+To attach the same context to every turn without threading it through each call site, pass `prepareSend`. It runs right before each send and returns the (possibly augmented) turn:
+
+```ts
+const agent = useEveAgent({
+  prepareSend: (input) => ({
+    ...input,
+    clientContext: { route: location.pathname },
+  }),
+});
+```
+
+## Lifecycle callbacks
+
+The binding takes a few per-turn callbacks:
+
+- `onEvent(event)`: fires for each Eve stream event as it arrives.
+- `onError(error)`: fires with the last `Error` when a turn fails.
+- `onFinish(snapshot)`: fires with the final snapshot once a turn settles.
+- `onSessionChange(session)`: fires when the session cursor advances. Persist it to resume across reloads.
+
+```ts
+const agent = useEveAgent({
+  onEvent: (event) => console.debug(event.type),
+  onError: (error) => console.error(error.message),
+  onFinish: (snapshot) => console.log(snapshot.status),
+});
+```
+
+Two more options tune turn behavior:
+
+- `optimistic` (default `true`): projects submitted user messages into `data` before Eve confirms them with a `message.received` event. These are reducer-facing projection events only; `events` stays the authoritative Eve stream.
+- `maxReconnectAttempts` (default `3`): stream reconnection budget per turn.
+
+## Custom reducer
+
+The default reducer projects events into `{ messages }` (`EveMessageData`). To shape `data` differently, pass a `reducer` implementing `EveAgentReducer<TData>`:
+
+```ts
+import { useEveAgent } from "eve/svelte";
+import type { EveAgentReducer } from "eve/svelte";
+
+interface ToolLog {
+  readonly toolCalls: number;
+}
+
+const toolCounter: EveAgentReducer<ToolLog> = {
+  initial: () => ({ toolCalls: 0 }),
+  reduce: (data, event) =>
+    event.type === "actions.requested" ? { toolCalls: data.toolCalls + 1 } : data,
+};
+
+const agent = useEveAgent({ reducer: toolCounter });
+// agent.data is ToolLog
+```
+
+`reduce(data, event)` receives both authoritative Eve stream events and client projection events (`client.message.submitted`, `client.message.failed`, `client.input.responded`). Handle the client events too if you want optimistic and HITL state in your projection. Otherwise, return `data` unchanged for them.
+
 ## What to read next
 
 - [SvelteKit](./sveltekit): Vite plugin setup

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

@@ -3,7 +3,7 @@ title: "useEveAgent (Vue)"
 description: "Vue composable that drives an Eve agent session from the browser."
 ---
 
-`useEveAgent()` from `eve/vue` is how a Vue app talks to an Eve session. It opens a long-lived session and sends turns, and it folds every stream event into reactive data you can bind in a template. Nuxt auto-imports it through the [module](./nuxt), and the [frontend overview](./overview) covers the shared model.
+`useEveAgent()` from `eve/vue` is how a Vue app talks to an Eve session. It opens a long-lived session, sends turns, and folds every stream event into reactive data you can bind in a template. Nuxt auto-imports it through the [module](./nuxt), and the [frontend overview](./overview) covers the shared model.
 
 ## Basic usage
 
@@ -25,18 +25,18 @@ const { data } = useEveAgent();
 
 ## What it returns
 
-| Property  | Type                              | Description                                                               |
-| --------- | --------------------------------- | ------------------------------------------------------------------------- |
-| `data`    | `ComputedRef<TData>`              | Projected state. With the default reducer, `EveMessageData` (`messages`). |
-| `status`  | `ComputedRef<UseEveAgentStatus>`  | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
-| `error`   | `ComputedRef<Error \| undefined>` | Last transport-level error.                                               |
-| `events`  | `ComputedRef<...>`                | Raw server events for this session.                                       |
-| `session` | `ComputedRef<SessionState>`       | Snapshot of session state.                                                |
-| `send`    | `(input) => Promise`              | Send text or a full turn (multi-part, attachments, HITL responses).       |
-| `stop`    | `() => void`                      | Abort the in-flight request.                                              |
-| `reset`   | `() => void`                      | Clear state and start a new session.                                      |
+| Property  | Type                                               | Description                                                               |
+| --------- | -------------------------------------------------- | ------------------------------------------------------------------------- |
+| `data`    | `ComputedRef<TData>`                               | Projected state. With the default reducer, `EveMessageData` (`messages`). |
+| `status`  | `ComputedRef<UseEveAgentStatus>`                   | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
+| `error`   | `ComputedRef<Error \| undefined>`                  | Last transport-level error.                                               |
+| `events`  | `ComputedRef<readonly HandleMessageStreamEvent[]>` | Raw server events for this session.                                       |
+| `session` | `ComputedRef<SessionState>`                        | Snapshot of session state.                                                |
+| `send`    | `(input: SendTurnPayload) => Promise<void>`        | Send text or a full turn (multi-part, attachments, HITL responses).       |
+| `stop`    | `() => void`                                       | Abort the in-flight request.                                              |
+| `reset`   | `() => void`                                       | Clear state and start a new session.                                      |
 
-The first five are `ComputedRef`s; the rest are methods. Destructure whatever you need: refs keep their reactivity through destructuring. Read them with `.value` in `<script>`, and unwrapped in `<template>`.
+The first five are `ComputedRef`s; the rest are methods. Destructure whatever you need, since refs keep their reactivity through destructuring. Read them with `.value` in `<script>`, and unwrapped in `<template>`.
 
 ## Send a message
 
@@ -64,7 +64,7 @@ async function handleSubmit() {
 </template>
 ```
 
-For anything beyond plain text, reach for `send()`. Attachments follow the AI SDK `UserContent` format:
+For anything beyond plain text, reach for `send()`. Attachments follow the AI SDK `UserContent` format. Send file data as a base64 `data:` URL so it survives the JSON transport:
 
 ```vue
 <script setup lang="ts">
@@ -75,10 +75,12 @@ const { send } = useEveAgent();
 async function onFileChange(event: Event) {
   const file = (event.target as HTMLInputElement).files?.[0];
   if (!file) return;
+  const bytes = new Uint8Array(await file.arrayBuffer());
+  const base64 = btoa(String.fromCodePoint(...bytes));
   await send({
     message: [
       { type: "text", text: "Describe this image." },
-      { type: "file", data: new Uint8Array(await file.arrayBuffer()), mediaType: file.type },
+      { type: "file", data: `data:${file.type};base64,${base64}`, mediaType: file.type },
     ],
   });
 }
@@ -87,7 +89,30 @@ async function onFileChange(event: Event) {
 
 ## Human-in-the-loop prompts
 
-A tool opts into approval with `needsApproval` ([Tools](../../tools)). When it triggers, the pending request shows up as a `dynamic-tool` part on the latest message. Read it and answer with `send({ inputResponses })`. That find-and-answer flow is the same across every framework, so the full example lives in the [Frontend overview](./overview#human-in-the-loop-prompts).
+A tool opts into approval with `needsApproval` ([Tools](../../tools)). When it triggers, the pending request shows up as a `dynamic-tool` part on the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `send({ inputResponses })`:
+
+```ts
+import type { EveDynamicToolPart, EveMessagePart } from "eve/vue";
+
+const { data, send } = useEveAgent();
+
+const isDynamicToolPart = (part: EveMessagePart): part is EveDynamicToolPart =>
+  part.type === "dynamic-tool";
+
+const request = data.value.messages
+  .at(-1)
+  ?.parts.filter(isDynamicToolPart)
+  .map((part) => part.toolMetadata?.eve?.inputRequest)
+  .find((value) => value !== undefined);
+
+if (request) {
+  await send({
+    inputResponses: [{ requestId: request.requestId, optionId: "approve" }],
+  });
+}
+```
+
+The find-and-answer flow is the same across every framework. The [React hook reference](./overview) covers the longer walkthrough.
 
 ## Stop, reset, and resume
 
@@ -116,6 +141,74 @@ const agent = useEveAgent({
 });
 ```
 
+## Attach page context per turn
+
+`clientContext` adds ephemeral context for the next model call and nothing more. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, never dispatches a turn on its own, and never lands in durable session history. Pass it to `send()`:
+
+```ts
+await send({
+  message: "What should I do on this screen?",
+  clientContext: { route: "/billing", plan: "pro", seatsUsed: 4 },
+});
+```
+
+To attach the same context to every turn without threading it through each call site, pass `prepareSend`. It runs right before each send and returns the (possibly augmented) turn:
+
+```ts
+const agent = useEveAgent({
+  prepareSend: (input) => ({
+    ...input,
+    clientContext: { route: location.pathname },
+  }),
+});
+```
+
+## Lifecycle callbacks
+
+The composable takes a few per-turn callbacks:
+
+- `onEvent(event)`: fires for each Eve stream event as it arrives.
+- `onError(error)`: fires with the last `Error` when a turn fails.
+- `onFinish(snapshot)`: fires with the final snapshot once a turn settles.
+- `onSessionChange(session)`: fires when the session cursor advances. Persist it to resume across reloads.
+
+```ts
+const agent = useEveAgent({
+  onEvent: (event) => console.debug(event.type),
+  onError: (error) => console.error(error.message),
+  onFinish: (snapshot) => console.log(snapshot.status),
+});
+```
+
+Two more options tune turn behavior:
+
+- `optimistic` (default `true`): projects submitted user messages into `data` before Eve confirms them with a `message.received` event. These are reducer-facing projection events only; `events` stays the authoritative Eve stream.
+- `maxReconnectAttempts` (default `3`): stream reconnection budget per turn.
+
+## Custom reducer
+
+The default reducer projects events into `{ messages }` (`EveMessageData`). To shape `data` differently, pass a `reducer` implementing `EveAgentReducer<TData>`:
+
+```ts
+import { useEveAgent } from "eve/vue";
+import type { EveAgentReducer } from "eve/vue";
+
+interface ToolLog {
+  readonly toolCalls: number;
+}
+
+const toolCounter: EveAgentReducer<ToolLog> = {
+  initial: () => ({ toolCalls: 0 }),
+  reduce: (data, event) =>
+    event.type === "actions.requested" ? { toolCalls: data.toolCalls + 1 } : data,
+};
+
+const agent = useEveAgent({ reducer: toolCounter });
+// agent.data.value is ToolLog
+```
+
+`reduce(data, event)` receives both authoritative Eve stream events and client projection events (`client.message.submitted`, `client.message.failed`, `client.input.responded`). Handle the client events too if you want optimistic and HITL state in your projection. Otherwise, return `data` unchanged for them.
+
 ## What to read next
 
 - [Nuxt](./nuxt): module setup

package/docs/guides/hooks.md

@@ -3,7 +3,7 @@ title: "Hooks"
 description: "Subscribe to runtime stream events from agent/hooks/."
 ---
 
-Hooks are Eve's authored extension points for the runtime event stream. A hook subscribes to stream events and runs side effects after each event is durably recorded: audit logging, metrics and alerting, or persisting every session and message to your own database for analytics. Reach for one when you want to observe what the agent does without writing a tool, a context provider, or a channel adapter handler.
+Hooks are Eve's authored extension points for the runtime event stream. A hook subscribes to stream events and runs side effects after each event is durably recorded, such as audit logging, metrics and alerting, or persisting every session and message to your own database for analytics. Reach for one to observe what the agent does without writing a tool, a context provider (a value made available across a step), or a channel adapter handler (a handler defined on a channel's adapter; see [Channels](../channels)).
 
 ## Define a hook
 
@@ -22,31 +22,13 @@ export default defineHook({
 });
 ```
 
-The slug is the path-relative basename: `agent/hooks/audit.ts` becomes `"audit"`, and `agent/hooks/auth/load-profile.ts` becomes `"auth/load-profile"`.
+The slug is the path-relative basename. `agent/hooks/audit.ts` becomes `"audit"`, and `agent/hooks/auth/load-profile.ts` becomes `"auth/load-profile"`.
 
-`defineHook`, `HookDefinition`, and `HookContext` live on `eve/hooks`. The `defineState` helper lives on `eve/context`.
+`defineHook`, `HookDefinition`, and `HookContext` live on `eve/hooks`.
 
-## Shape
+A hook file declares stream-event subscribers under the `events` map, keyed by event type, with `*` matching every event. Subscribe to any event in the runtime stream vocabulary documented in [Sessions, runs and streaming](../concepts/sessions-runs-and-streaming), including the lifecycle events `session.started`, `turn.completed`, `message.completed`, and `action.result`. Handlers are observe-only. They cannot inject model context. To contribute runtime model messages, use `defineDynamic` and `defineInstructions` in `agent/instructions/`.
 
-A hook file declares stream-event subscribers under the `events` map:
-
-```ts
-defineHook({
-  events: {
-    "session.started"(event, ctx) {
-      /* ... */
-    },
-    "turn.completed"(event, ctx) {
-      /* ... */
-    },
-    "*"(event, ctx) {
-      /* wildcard: fires for every event */
-    },
-  },
-});
-```
-
-Handlers are observe-only: they cannot inject model context. To contribute runtime model messages, use `defineDynamic` + `defineInstructions` in `agent/instructions/`.
+## Hook structure and context
 
 Every handler receives the same `HookContext`:
 
@@ -89,51 +71,23 @@ export default defineHook({
 
 Returns `undefined` when the result doesn't match, or when `isError` is `true`. For authored tools the return includes `{ output, toolName, callId }` with `output` typed as the tool's `TOutput`. For connections it includes `{ output, toolName, connectionToolName, callId }` with `output` as `unknown`.
 
-## Stream events
-
-Side-effect-only handlers for accepted runtime events. Subscribe by event type, or use `*` for every event:
-
-```ts title="agent/hooks/observability.ts"
-import { defineHook } from "eve/hooks";
-import { datadogCounter } from "../lib/datadog";
-import { postToHoneycomb } from "../lib/honeycomb";
-
-export default defineHook({
-  events: {
-    async "session.started"(_event, ctx) {
-      await postToHoneycomb({ event: "session.started", sessionId: ctx.session.id });
-    },
-    async "message.completed"(event) {
-      await postToHoneycomb({ event: "message.completed", payload: event.data });
-    },
-    async "*"(event) {
-      datadogCounter(`eve.event.${event.type}`).increment();
-    },
-  },
-});
-```
-
-### Execution order
+## Execution order
 
 When a stream event fires, three things happen in order:
 
-1. Emit: the channel adapter handler runs, then the event is written to the durable stream.
-2. Hooks: stream-event hooks fire (typed handlers first, then the `*` wildcard). Return values are ignored.
-3. Dynamic tool resolvers: resolvers subscribed to the event type run and update the tool set.
+1. Emit. The channel adapter handler runs, then the event is written to the durable stream.
+2. Hooks. Stream-event hooks fire (typed handlers first, then the `*` wildcard). Return values are ignored.
+3. Dynamic tool resolvers. Resolvers subscribed to the event type run and update the tool set.
 
 Hooks always run after the event is durably recorded, so if a hook throws, the stream stays consistent.
 
-## Errors
-
-| Stage      | On throw                                                                                                                                                           |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `events.*` | Propagates through the emit composer and surfaces as `turn.failed`. If a hook subscribed to a failure-cascade event also throws, it escalates to `session.failed`. |
+## What happens when a hook throws
 
-For belt-and-suspenders semantics inside a hook, wrap the body in `try`/`catch`. Eve treats a thrown hook as a real failure.
+A thrown handler propagates through the emit composer and surfaces as `turn.failed`. If a hook subscribed to a failure-cascade event also throws, it escalates to `session.failed`. For belt-and-suspenders semantics inside a hook, wrap the body in `try`/`catch`. Eve treats a thrown hook as a real failure.
 
 ## Subagent isolation
 
-Subagents may carry their own `agent/hooks/` directory. Subagent hooks fire only inside the subagent scope: parent-agent hooks do not fire for subagent turns, and subagent hooks see only the subagent's own context.
+Subagents may carry their own `agent/hooks/` directory. Subagent hooks fire only inside the subagent scope. Parent-agent hooks do not fire for subagent turns, and subagent hooks see only the subagent's own context.
 
 ## Hook vs tool vs provider
 
@@ -150,5 +104,5 @@ Stream-event hooks and channel adapter event handlers are structurally identical
 
 - [Tools](../tools)
 - [Context control](../concepts/context-control)
-- [Session context](./session-context)
-- [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming)
+- [Session context](../reference/typescript-api)
+- [Sessions, runs and streaming](../concepts/sessions-runs-and-streaming)

package/docs/guides/instrumentation.md

@@ -1,13 +1,15 @@
 ---
 title: "instrumentation.ts"
-description: "Trace an agent with OpenTelemetry, read the workflow run tags Eve emits, and debug discovery with eve info and the error catalog."
+description: "Trace an agent with OpenTelemetry in instrumentation.ts, read the workflow run tags Eve emits, and debug discovery with eve info and the common-failures table."
 ---
 
 `instrumentation.ts` is where you configure how an Eve agent is observed. The framework auto-discovers `agent/instrumentation.ts` and runs it at server startup before any agent code. Its presence implicitly enables telemetry, so there is no separate `isEnabled` toggle.
 
+If you intend to export telemetry, review the exporter destination, data categories, and required legal approvals before enabling telemetry.
+
 ## Three observability surfaces
 
-Eve observes an agent through three distinct surfaces. They do not all live in this file, and they write to different places, so it helps to keep them apart:
+Eve observes an agent through three distinct surfaces. They do not all live in this file, and they write to different places:
 
 | Surface                          | Configured in `instrumentation.ts`?                         | What it is                                                                                                                                                    |
 | -------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -15,7 +17,7 @@ Eve observes an agent through three distinct surfaces. They do not all live in t
 | **OpenTelemetry export**         | Yes: `setup`, `recordInputs`, `recordOutputs`, `functionId` | Where AI SDK spans are exported and what they record.                                                                                                         |
 | **Runtime context events**       | Yes: `events["step.started"]`                               | Per-model-call values written into the AI SDK's runtime context, which the AI SDK carries onto its spans.                                                     |
 
-The two configurable surfaces send AI SDK spans to your OpenTelemetry backend. Workflow run tags are a separate system: they live on the Vercel Workflow run and are queryable in the Workflow dashboard, not on your OTel spans. The sections below cover what you configure here; [Workflow run tags](#workflow-run-tags) documents what Eve emits on its own.
+The two configurable surfaces send AI SDK spans to your OpenTelemetry backend. Workflow run tags are a separate system, queryable in the Workflow dashboard rather than on your OTel spans. The sections below cover what you configure here; [Workflow run tags](#workflow-run-tags) documents what Eve emits on its own.
 
 ## Define instrumentation
 
@@ -40,7 +42,7 @@ Export the result of `defineInstrumentation` as the default export.
 
 ## OpenTelemetry
 
-The `setup` callback is invoked by the framework at server startup with the resolved agent name. Use it to register your OTel provider (for example `registerOTel` from `@vercel/otel`). The `context.agentName` is resolved at compile time from your project (the package's `name`, falling back to the app directory name), so you never need to hard-code a service name.
+Use the `setup` callback to register your OTel provider (for example `registerOTel` from `@vercel/otel`). The framework invokes it at server startup with the resolved agent name. `context.agentName` is resolved at compile time from your project (the package's `name`, falling back to the app directory name), so you never hard-code a service name.
 
 Any OTel-compatible backend works (Braintrust, Honeycomb, Datadog, Jaeger). Install the exporter package you need and configure it in the callback.
 
@@ -50,11 +52,15 @@ Three more fields control what the AI SDK records inside those spans (see the AI
 - `recordOutputs` records model outputs on spans (defaults to `true`). Set it to `false` to disable output recording.
 - `functionId` overrides the function name on spans (defaults to the agent name).
 
+For sensitive, regulated, or production data, set `recordInputs` and `recordOutputs` to `false` unless you have reviewed the exporter and its data-retention path.
+
+You are responsible for ensuring any observability or eval provider is approved for the data exported to it.
+
 The third configurable surface, [runtime context events](#runtime-context), attaches per-model-call values to these spans.
 
 ## Runtime context
 
-_Runtime context_ is an [AI SDK concept](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text): a user-defined object that flows through a generation lifecycle. Eve exposes it through `events["step.started"]`, a callback that runs once Eve has assembled the model input for an attempt and returns `{ runtimeContext }`. Because Eve registers the AI SDK's OpenTelemetry integration with runtime context enabled, those returned values ride onto the model-call span and its children. That is the reason this surface exists. The returned field is named `runtimeContext`, not `metadata`, because AI SDK v7 carries per-call attributes on runtime context rather than a dedicated metadata field.
+_Runtime context_ is an [AI SDK concept](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text): a user-defined object that flows through a generation lifecycle. Eve exposes it through `events["step.started"]`, a callback that runs once Eve has assembled the model input for an attempt and returns `{ runtimeContext }`. Because Eve registers the AI SDK's OpenTelemetry integration with runtime context enabled, those returned values ride onto the model-call span and its children. The field is named `runtimeContext`, not `metadata`, because AI SDK v7 carries per-call attributes on runtime context rather than a dedicated metadata field.
 
 Use it when the values depend on the current session, turn, step, channel, or model input:
 
@@ -80,8 +86,6 @@ export default defineInstrumentation({
 });
 ```
 
-For authored channels, Eve emits compiler-owned typings keyed by the channel filename. A file at `agent/channels/support.ts` narrows as `channel:support`, either by checking `input.channel.kind === "channel:support"` or by using `isChannel(input.channel, supportChannel)`.
-
 The callback receives:
 
 - `session`: the session id, current and initiator auth, and parent session lineage when this is a child run
@@ -90,7 +94,7 @@ The callback receives:
 - `channel`: the channel's `kind` and the metadata projected by the active channel
 - `modelInput`: the final instructions and messages passed to the model call
 
-A channel exposes its identity through `kind`, the discriminant you narrow on. For authored channels it is `channel:<name>`, where `<name>` is the channel's filename under `agent/channels/`, so `agent/channels/support.ts` is `channel:support`. Framework channels use `http`, `schedule`, or `subagent`; an unrecognized or absent kind normalizes to `unknown`. The kind is also emitted as the `eve.channel.kind` span attribute.
+A channel exposes its identity through `kind`, the discriminant you narrow on. For authored channels it is `channel:<name>`, where `<name>` is the channel's filename under `agent/channels/`, so `agent/channels/support.ts` is `channel:support`. Framework channels use `http`, `schedule`, or `subagent`, and an unrecognized or absent kind normalizes to `unknown`. The kind is also emitted as the `eve.channel.kind` span attribute. Eve emits compiler-owned typings keyed by the channel filename, so you can narrow either by checking `input.channel.kind === "channel:support"` or by using `isChannel(input.channel, supportChannel)`.
 
 Channel metadata is channel-owned. Built-in channels expose only the fields they choose to make observable; Slack, for example, projects `channelId`, `teamId`, `threadTs`, and `triggeringUserId` from its durable channel state. User-authored channels expose their own projection by returning `metadata(state)` from `defineChannel`. Runtime instrumentation never falls back to raw channel state.
 
@@ -115,7 +119,7 @@ Eve creates the `ai.eve.turn` parent span per turn and passes enriched telemetry
 
 Separately from OpenTelemetry, Eve tags every workflow run with reserved `$eve.*` attributes. These live on the Vercel Workflow run, queryable in the Workflow dashboard, not on OTel spans, and you do not configure them: they are framework-owned and emitted automatically on every session, turn, and subagent run, whether or not an `instrumentation.ts` file is present. Authored code cannot set or override the `$eve.` namespace.
 
-Their job is to let a dashboard reconstruct the tree of runs behind a single agent invocation and surface model and token usage without reading run bodies.
+They let a dashboard reconstruct the tree of runs behind a single agent invocation and surface model and token usage without reading run bodies.
 
 Structural tags describe each run's place in the tree:
 
@@ -134,7 +138,9 @@ Per-turn usage tags are written on each step of a turn, accumulating cumulative
 
 Tag writes are best-effort: a failure is logged once per process and then swallowed, so a broken tag emit never breaks the agent.
 
-These tags power the **Agent Runs** tab in the Vercel dashboard. When you deploy on Vercel, the platform auto-detects `eve` as the framework and surfaces an Agent Runs view under your project's **Observability** tab, where you can browse sessions and drill into each conversation's trace — no `instrumentation.ts` required. The tab is currently gated per team; see [Deployment](./deployment#view-runs-in-the-dashboard) for enablement. Agent Runs is separate from the OpenTelemetry export above: use OTel when you want spans in Braintrust, Datadog, or another third-party backend.
+These tags power the **Agent Runs** tab in the Vercel dashboard. When you deploy on Vercel, the platform auto-detects `eve` as the framework and surfaces an Agent Runs view under your project's **Observability** tab, where you can browse sessions and drill into each conversation's trace, with no `instrumentation.ts` required. The tab is currently gated per team. See [Deployment](./deployment#view-runs-in-the-dashboard) for enablement. Agent Runs is separate from the OpenTelemetry export above. Use OTel when you want spans in Braintrust, Datadog, or another third-party backend.
+
+Note: By default, telemetry records full message history and model outputs You may need to disclose these data flows in your privacy materials if utilized.
 
 ## Debugging
 
@@ -151,17 +157,17 @@ When `eve build` fails on discovery errors, the CLI prints the full diagnostics
 
 ### Common failures
 
-| Symptom                                       | Likely cause and fix                                                                                                                                                                                     |
-| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Tool not discovered (the model never sees it) | Run `eve info`. Confirm the file is in the right slot (`agent/tools/<name>.ts`) and default-exports `defineTool(...)`, and check `.eve/diagnostics.json` for shape errors. `schedules/` are root-only.   |
-| Model won't call a tool it should             | Tighten the tool `description` and `inputSchema`; put procedural guidance in a [skill](../skills), not the description. Confirm it's in the active set with `eve info`.                                  |
-| Stuck on `session.waiting`                    | The turn is parked on an approval, a question, or a connection sign-in. Answer it, or POST a follow-up with the `continuationToken` (a stale token is rejected).                                         |
-| 401 on production routes                      | Expected: auth fails closed. Replace `placeholderAuth()`, and set `VERCEL_PROJECT_ID` and environment so `vercelOidc()` accepts user tokens. See [Auth & route protection](./auth-and-route-protection). |
-| Build fails with discovery errors             | Read the printed diagnostics and `.eve/diagnostics.json`; confirm the root-vs-subagent boundary is valid and secrets come from env vars.                                                                 |
+| Symptom                                       | Likely cause and fix                                                                                                                                                                                       |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tool not discovered (the model never sees it) | Run `eve info`. Confirm the file is in the right slot (`agent/tools/<name>.ts`) and default-exports `defineTool(...)`, and check `.eve/diagnostics.json` for shape errors. `schedules/` are root-only.     |
+| Model won't call a tool it should             | Tighten the tool `description` and `inputSchema`; put procedural guidance in a [skill](../skills), not the description. Confirm it's in the active set with `eve info`.                                    |
+| Stuck on `session.waiting`                    | The turn is parked on an approval, a question, or a connection sign-in. Answer it, or POST a follow-up with the `continuationToken` (a stale token is rejected).                                           |
+| 401 on production routes                      | Expected: auth fails closed. Replace `placeholderAuth()`, and set `VERCEL_PROJECT_ID` and environment so `vercelOidc()` accepts user tokens. See [Auth and route protection](./auth-and-route-protection). |
+| Build fails with discovery errors             | Read the printed diagnostics and `.eve/diagnostics.json`; confirm the root-vs-subagent boundary is valid and secrets come from env vars.                                                                   |
 
 ## What to read next
 
 - [`agent.ts`](../agent-config)
 - [Hooks](./hooks): observe the runtime event stream
-- [Dev TUI](./dev-tui): drive the agent locally
+- [Local Development](./dev-tui): drive the agent locally
 - [Evals](../evals/overview): repeatable scored checks