eve 0.34.0 → 0.36.0

package/docs/guides/frontend/sveltekit.mdx

@@ -69,21 +69,12 @@ With the plugin in `vite.config.ts`, components call [`useEveAgent`](./use-eve-a
 </form>
 ```
 
-The default eve channel is fail-closed. With no `agent/channels/eve.ts` authored, eve registers `eveChannel({ auth: [vercelOidc(), localDev(), placeholderAuth()] })`: `vercelOidc()` gets the first chance to resolve a Vercel caller, `localDev()` authenticates while the process is an `eve dev` or `vercel dev` server, and everything else gets a `401`. To set your own auth policy, add `agent/channels/eve.ts`:
-
-```ts title="agent/channels/eve.ts"
-import { eveChannel } from "eve/channels/eve";
-import { localDev, vercelOidc } from "eve/channels/auth";
-
-export default eveChannel({ auth: [vercelOidc(), localDev()] });
-```
-
-For a public demo, use `none()` (also from `eve/channels/auth`) to skip authentication. See [Channels](../../channels/overview) and [Auth & route protection](../auth-and-route-protection).
+The browser still needs a production authentication policy. See [Authenticate browser requests](./overview#authenticate-browser-requests) for the default fail-closed behavior and channel configuration.
 
 ## Dev vs deploy topology
 
 - **Local dev.** `npm run dev` boots the eve dev server next to SvelteKit and proxies the eve routes to it, so the browser only ever hits the SvelteKit origin. `npm run build && npm run preview` behaves the same way: the preview server gets its own eve route proxy and either reuses the shared eve server or starts one.
-- **Vercel.** The SvelteKit app and the eve runtime deploy as a single project. The web app is public; the eve runtime sits behind it on the same origin. Use `eveBuildCommand` for a project-specific agent build:
+- **Vercel.** The SvelteKit app and the eve runtime deploy as a single project. On Vercel builds the plugin adds Build Output [`services`](https://vercel.com/docs/services) for eve and a `routes` entry that sends `/eve/v1/**` to that service before filesystem routing; the SvelteKit app remains the default app. No `vercel.json` is required. By default the generated service runs the installed eve binary from the SvelteKit app's dependencies, so the agent directory does not need its own `package.json`. When the agent needs its own build step, set `eveBuildCommand`:
 
   ```ts
   export default defineConfig({
@@ -104,6 +95,27 @@ For a public demo, use `none()` (also from `eve/channels/auth`) to skip authenti
   });
   ```
 
+## Managing vercel.json yourself
+
+When `vercel.json` declares [`services`](https://vercel.com/docs/services), the plugin generates nothing and your configuration owns routing. It must include the eve service (`framework: "eve"`) and a rewrite that exposes the eve transport, or the build fails:
+
+```json title="vercel.json"
+{
+  "services": {
+    "web": { "root": ".", "framework": "sveltekit" },
+    "eve": { "root": "agent", "framework": "eve", "buildCommand": "eve build" }
+  },
+  "rewrites": [{ "source": "/eve/v1/(.*)", "destination": { "service": "eve" } }]
+}
+```
+
+### Migrating from experimentalServices
+
+Earlier versions of the plugin wrote the legacy `experimentalServices` field into `vercel.json`. Vercel no longer routes that model, so the plugin now ignores the field and warns when it sees one. Migrate either way:
+
+- **Generated (default).** Delete `vercel.json` (or just its `experimentalServices` block) and set the project's Framework Preset back to SvelteKit. The plugin generates the eve service and its routing on every Vercel build.
+- **Hand-maintained.** Replace `experimentalServices` with the stable `services` and `rewrites` shown above, and keep the Services Framework Preset.
+
 ## What to read next
 
 - [`useEveAgent` (Svelte)](./use-eve-agent-svelte): the binding API

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

@@ -1,43 +1,15 @@
 ---
 title: "useEveAgent (Svelte)"
-description: "Svelte 5 binding that drives an eve agent session from the browser."
+description: "Use the eve Svelte binding and its Svelte-specific reactive interface."
 ---
 
-`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.
+`useEveAgent()` from `eve/svelte` exposes the shared eve frontend client through Svelte 5 reactive getters and methods. Read the [frontend overview](./overview) for session behavior, messages, human input, authorization, callbacks, reducers, and persistence. This page covers the Svelte-specific interface.
 
-## Basic usage
-
-Import from `eve/svelte` and read the reactive getters directly. No `$` prefix:
-
-```svelte
-<script lang="ts">
-  import { useEveAgent } from "eve/svelte";
-
-  const agent = useEveAgent();
-</script>
-
-{#each agent.data.messages as message}
-  <p>{message.role}: {JSON.stringify(message.parts)}</p>
-{/each}
-```
-
-## What it returns
+On SvelteKit, register the [`eveSvelteKit` Vite plugin](./sveltekit) to mount the agent routes on the application origin.
 
-| 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 MessageStreamEvent[]`               | Raw server events for this session.                                       |
-| `session` | `ClientSessionState \| undefined`             | Fixed session ID and stream cursor.                                       |
-| `send`    | `(message, options?) => Promise<void>`        | Send text or a multi-part message.                                        |
-| `respond` | `(inputResponses, options?) => Promise<void>` | Answer pending HITL input requests.                                       |
-| `stop`    | `() => void`                                  | Abort the client's in-flight stream.                                      |
-| `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 `$`.
+## Basic usage
 
-## Send a message
+Call the binding once for a conversation and read its reactive getters directly. The returned object is not a Svelte store, so its fields do not use the `$` prefix:
 
 ```svelte
 <script lang="ts">
@@ -45,39 +17,51 @@ These state fields are reactive getters, so read them straight from templates, `
 
   const agent = useEveAgent();
   let message = $state("");
+  let isBusy = $derived(agent.status === "submitted" || agent.status === "streaming");
 
   async function handleSubmit() {
     const text = message.trim();
-    if (!text) return;
+    if (!text || isBusy) return;
     message = "";
     await agent.send(text);
   }
 </script>
 
+{#each agent.data.messages as item}
+  <p>{item.role}: {JSON.stringify(item.parts)}</p>
+{/each}
+
 <form onsubmit={(event) => {
   event.preventDefault();
   void handleSubmit();
 }}>
-  <input bind:value={message} placeholder="Type a message..." />
-  <button type="submit">Send</button>
+  <input bind:value={message} disabled={isBusy} />
+  <button type="submit" disabled={isBusy}>Send</button>
 </form>
 ```
 
-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:
+## What it returns
 
-```ts
-const bytes = new Uint8Array(await file.arrayBuffer());
-const base64 = btoa(String.fromCodePoint(...bytes));
+The state fields are reactive getters; the commands are ordinary methods:
 
-await agent.send([
-  { type: "text", text: "Describe this image." },
-  { type: "file", data: `data:${file.type};base64,${base64}`, mediaType: file.type },
-]);
-```
+| Property                           | Svelte shape                      |
+| ---------------------------------- | --------------------------------- |
+| `data`                             | `TData`                           |
+| `status`                           | `UseEveAgentStatus`               |
+| `error`                            | `Error \| undefined`              |
+| `events`                           | `readonly MessageStreamEvent[]`   |
+| `session`                          | `ClientSessionState \| undefined` |
+| `send`, `respond`, `stop`, `reset` | Methods                           |
+
+Read the getters directly in templates, `$derived`, or `$effect`. The [shared returned-state reference](./overview#returned-state) describes what each value and command does.
+
+## Send a message
+
+Call `agent.send(text)` for text or pass content parts for attachments. The API and transport behavior match the [shared sending guide](./overview#sending-and-streaming); only reactive access differs in Svelte.
 
 ## Human-in-the-loop prompts
 
-A tool opts into approval with `approval` ([Tools](../../tools)). When one fires, the pending request rides along on a `dynamic-tool` part at `part.toolMetadata?.eve?.inputRequest`. Scan every message because an unrelated turn can add newer messages while the approval stays open, then answer through the same session with `agent.respond(inputResponses)`:
+Pending requests appear in `agent.data.messages`. Use the Svelte exports when narrowing message parts, then answer through `agent.respond()`:
 
 ```svelte
 <script lang="ts">
@@ -118,101 +102,30 @@ A tool opts into approval with `approval` ([Tools](../../tools)). When one fires
 {/each}
 ```
 
-For a question with `allowFreeform`, bind a text input and send `{ requestId, text }`. The [React hook reference](./overview) covers the shared behavior.
+See [Human-in-the-loop prompts](./overview#human-in-the-loop-prompts) for request semantics and rendering guidance.
 
 ## Stop, reset, and resume
 
-`stop()` aborts the in-flight stream; the server-side turn keeps running and remains attachable — to stop the turn itself, POST the session's [cancel route](../../channels/eve#routes). `reset()` wipes state and starts a fresh session. To resume across reloads, hand `initialSession` the state you saved earlier and use `onSessionChange` to persist the cursor as it advances:
-
-```ts
-const agent = useEveAgent({
-  initialSession: savedSessionState,
-  initialEvents: savedEvents,
-  onSessionChange: (session) => {
-    localStorage.setItem("eve-session", JSON.stringify(session));
-  },
-});
-```
+Call `agent.stop()` to detach the browser stream without cancelling server-side work, and `agent.reset()` to clear local state and start a new session. Pass `initialSession` and `initialEvents` to restore a saved conversation. 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
 
-Point `host` at an eve server on a different origin, and pass credentials through `auth` or `headers`. When you supply a function, it re-resolves before every request:
-
-```ts
-const agent = useEveAgent({
-  host: "https://agent.example.com",
-  headers: async () => ({
-    authorization: `Bearer ${await getAccessToken()}`,
-  }),
-});
-```
+Pass `host`, `auth`, or `headers` to the binding using the same options as the other frontend bindings. See [Custom hosts and headers](./overview#custom-hosts-and-headers).
 
 ## 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("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 },
-  }),
-});
-```
+Pass `clientContext` to `send()` or `respond()`, or use `prepareSend` to add context before every turn. See [Attach page context per turn](./overview#attach-page-context-per-turn).
 
 ## 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),
-});
-```
-
-The `optimistic` option (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.
+Pass `onEvent`, `onError`, `onFinish`, or `onSessionChange` when the application needs lifecycle notifications. See [Lifecycle callbacks](./overview#lifecycle-callbacks) for callback timing and optimistic projection behavior.
 
 ## 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.
+Import `EveAgentReducer` from `eve/svelte` when projecting events into application-specific state. The resulting `agent.data` uses the reducer's `TData` type. See [Custom reducer](./overview#custom-reducer) for the reducer contract and client projection events.
 
 ## What to read next
 
-- [SvelteKit](./sveltekit): Vite plugin setup
-- [Frontend overview](./overview): the shared integration model
-- [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming)
+- [SvelteKit](./sveltekit): register the Vite plugin and mount the eve runtime.
+- [Frontend overview](./overview): use the shared frontend API.
+- [Sessions, runs, and streaming](../../concepts/sessions-runs-and-streaming): understand the underlying session protocol.

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

@@ -1,94 +1,66 @@
 ---
 title: "useEveAgent (Vue)"
-description: "Vue composable that drives an eve agent session from the browser."
+description: "Use the eve Vue composable and its Vue-specific reactive interface."
 ---
 
-`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.
+`useEveAgent()` from `eve/vue` exposes the shared eve frontend client as Vue computed refs and methods. Read the [frontend overview](./overview) for session behavior, messages, human input, authorization, callbacks, reducers, and persistence. This page covers the Vue-specific interface.
 
-## Basic usage
-
-Import the composable from `eve/vue`. Its state is exposed as `ComputedRef`s, so you read it unwrapped in templates:
-
-```vue
-<script setup lang="ts">
-import { useEveAgent } from "eve/vue";
-
-const { data } = useEveAgent();
-</script>
-
-<template>
-  <div v-for="message in data.messages" :key="message.id">
-    <p>{{ message.role }}: {{ message.parts }}</p>
-  </div>
-</template>
-```
+Nuxt users normally receive the composable as an auto-import after registering the [`eve/nuxt` module](./nuxt).
 
-## 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<readonly MessageStreamEvent[]>`   | Raw server events for this session.                                       |
-| `session` | `ComputedRef<ClientSessionState \| undefined>` | Fixed session ID and stream cursor.                                       |
-| `send`    | `(message, options?) => Promise<void>`         | Send text or a multi-part message.                                        |
-| `respond` | `(inputResponses, options?) => Promise<void>`  | Answer pending HITL input requests.                                       |
-| `stop`    | `() => void`                                   | Abort the client's in-flight stream.                                      |
-| `reset`   | `() => void`                                   | Clear state and start a new session.                                      |
+## Basic usage
 
-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
+Import the composable from `eve/vue`. Its state is exposed as `ComputedRef`s, so templates unwrap it automatically:
 
 ```vue
 <script setup lang="ts">
-import { ref } from "vue";
 import { useEveAgent } from "eve/vue";
+import { computed, ref } from "vue";
 
-const { send } = useEveAgent();
+const { data, status, send } = useEveAgent();
 const message = ref("");
+const isBusy = computed(() => status.value === "submitted" || status.value === "streaming");
 
 async function handleSubmit() {
   const text = message.value.trim();
-  if (!text) return;
+  if (!text || isBusy.value) return;
   message.value = "";
   await send(text);
 }
 </script>
 
 <template>
+  <div v-for="item in data.messages" :key="item.id">
+    <p>{{ item.role }}: {{ item.parts }}</p>
+  </div>
   <form @submit.prevent="handleSubmit">
-    <input v-model="message" placeholder="Type a message..." />
-    <button type="submit">Send</button>
+    <input v-model="message" :disabled="isBusy" />
+    <button type="submit" :disabled="isBusy">Send</button>
   </form>
 </template>
 ```
 
-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:
+## What it returns
 
-```vue
-<script setup lang="ts">
-import { useEveAgent } from "eve/vue";
+The state fields are computed refs; the commands are ordinary methods:
 
-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([
-    { type: "text", text: "Describe this image." },
-    { type: "file", data: `data:${file.type};base64,${base64}`, mediaType: file.type },
-  ]);
-}
-</script>
-```
+| Property                           | Vue shape                                      |
+| ---------------------------------- | ---------------------------------------------- |
+| `data`                             | `ComputedRef<TData>`                           |
+| `status`                           | `ComputedRef<UseEveAgentStatus>`               |
+| `error`                            | `ComputedRef<Error \| undefined>`              |
+| `events`                           | `ComputedRef<readonly MessageStreamEvent[]>`   |
+| `session`                          | `ComputedRef<ClientSessionState \| undefined>` |
+| `send`, `respond`, `stop`, `reset` | Methods                                        |
+
+Destructuring preserves reactivity because each state value remains a ref. Read refs with `.value` in `<script>` and without `.value` in a template. The [shared returned-state reference](./overview#returned-state) describes what each value and command does.
+
+## Send a message
+
+Call `send(text)` for text or pass content parts for attachments. The API and transport behavior match the [shared sending guide](./overview#sending-and-streaming); only reactive access differs in Vue.
 
 ## Human-in-the-loop prompts
 
-A tool opts into approval with `approval` ([Tools](../../tools)). When it triggers, the pending request shows up on a `dynamic-tool` part at `part.toolMetadata?.eve?.inputRequest`. Scan every message because an unrelated turn can add newer messages while the approval stays open, then answer through the same session with `respond(inputResponses)`:
+Pending requests appear in `data.value.messages`. Use the Vue exports when narrowing message parts, then answer through `respond()`:
 
 ```vue
 <script setup lang="ts">
@@ -132,101 +104,30 @@ const pendingRequests = computed(() =>
 </template>
 ```
 
-For a question with `allowFreeform`, bind a text input and send `{ requestId, text }`. The [React hook reference](./overview) covers the shared behavior.
+See [Human-in-the-loop prompts](./overview#human-in-the-loop-prompts) for request semantics and rendering guidance.
 
 ## Stop, reset, and resume
 
-`stop()` aborts the in-flight stream; the server-side turn keeps running and remains attachable — to stop the turn itself, POST the session's [cancel route](../../channels/eve#routes). `reset()` wipes state and starts a fresh session. To survive a reload, pass `initialSession` to restore a saved session and `onSessionChange` to persist the cursor as it moves:
-
-```ts
-const agent = useEveAgent({
-  initialSession: savedSessionState,
-  initialEvents: savedEvents,
-  onSessionChange: (session) => {
-    localStorage.setItem("eve-session", JSON.stringify(session));
-  },
-});
-```
+Call `stop()` to detach the browser stream without cancelling server-side work, and `reset()` to clear local state and start a new session. Pass `initialSession` and `initialEvents` to restore a saved conversation. 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
 
-When your eve server lives somewhere other than the same origin, point at it with `host` and attach credentials through `auth` or `headers`. Pass a function and it re-resolves before each request:
-
-```ts
-const agent = useEveAgent({
-  host: "https://agent.example.com",
-  headers: async () => ({
-    authorization: `Bearer ${await getAccessToken()}`,
-  }),
-});
-```
+Pass `host`, `auth`, or `headers` to the composable using the same options as the other frontend bindings. See [Custom hosts and headers](./overview#custom-hosts-and-headers).
 
 ## 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 in the second argument to `send()` or `respond()`:
-
-```ts
-await send("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 },
-  }),
-});
-```
+Pass `clientContext` to `send()` or `respond()`, or use `prepareSend` to add context before every turn. See [Attach page context per turn](./overview#attach-page-context-per-turn).
 
 ## 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),
-});
-```
-
-The `optimistic` option (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.
+Pass `onEvent`, `onError`, `onFinish`, or `onSessionChange` when the application needs lifecycle notifications. See [Lifecycle callbacks](./overview#lifecycle-callbacks) for callback timing and optimistic projection behavior.
 
 ## 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.
+Import `EveAgentReducer` from `eve/vue` when projecting events into application-specific state. The resulting `data` remains a `ComputedRef<TData>`. See [Custom reducer](./overview#custom-reducer) for the reducer contract and client projection events.
 
 ## What to read next
 
-- [Nuxt](./nuxt): module setup
-- [Frontend overview](./overview): the shared integration model
-- [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming)
+- [Nuxt](./nuxt): register the module and mount the eve runtime.
+- [Frontend overview](./overview): use the shared frontend API.
+- [Sessions, runs, and streaming](../../concepts/sessions-runs-and-streaming): understand the underlying session protocol.

package/docs/guides/instrumentation.md

@@ -1,5 +1,5 @@
 ---
-title: "instrumentation.ts"
+title: "Observability"
 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."
 ---
 
@@ -48,11 +48,11 @@ Any OTel-compatible backend works (Braintrust, PostHog, Raindrop, Arize, Honeyco
 
 Three more fields control what the AI SDK records inside those spans (see the AI SDK's [telemetry reference](https://ai-sdk.dev/docs/ai-sdk-core/telemetry)):
 
-- `recordInputs` records full message history on each step span (defaults to `true`). Set it to `false` if inputs contain sensitive content or you want to reduce span payload size.
-- `recordOutputs` records model outputs on spans (defaults to `true`). Set it to `false` to disable output recording.
+- `recordInputs` records full message history on each step span. It defaults to `false`; set it to `true` to include input content.
+- `recordOutputs` records model outputs on spans. It defaults to `false`; set it to `true` to include output content.
 - `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.
+eve records metadata without model or tool inputs and outputs by default. Enable either content category only after reviewing 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.
 
@@ -173,20 +173,20 @@ Tag writes are best-effort: a failure is logged once per process and then swallo
 
 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 [Deploy to Vercel](./deployment/vercel#inspect-agent-runs) for enablement. Agent Runs is separate from the OpenTelemetry export above. Use OTel when you want spans in Braintrust, PostHog, 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.
-
 ## Local traces
 
 Without an `instrumentation.ts`, `eve dev` records spans to disk — one trace per session, with turns, model steps, and tool calls. Read them two ways:
 
-- [`/traces`](dev-tui#inspect-traces) in the dev TUI: a live viewer that replays the trace as a conversation.
+- [`/traces`](dev-tui#logs-and-traces) in the dev TUI: a live trace viewer that replays captured content as a conversation.
 - [`eve traces`](../reference/cli#eve-traces): a span tree in the terminal, `eve traces ls` to list. Works after `eve dev` exits.
 
+Local traces omit model and tool inputs and outputs by default. Set `EVE_TRACES_CONTENT=on` in `.env.local` to capture that content.
+
 Writing `instrumentation.ts` replaces this: your `setup` takes over and nothing is recorded locally. For span attributes, retention, and the `EVE_TRACES*` variables, see [`eve traces`](../reference/cli#eve-traces).
 
 ## Debugging
 
-`eve info` is the fastest way to see what eve actually picked up: the active tools, skills, subagents, schedules, routes, and discovery diagnostics. eve also writes inspectable artifacts under `.eve/`, kept even when discovery hits errors:
+`eve info` is the fastest way to see what eve actually picked up: ordered static instructions with their roles, plus the active tools, skills, subagents, schedules, routes, and discovery diagnostics. Dynamic instruction results exist only at runtime and are not part of this static inspection. eve also writes inspectable artifacts under `.eve/`, kept even when discovery hits errors:
 
 | Artifact                        | Tells you                                   |
 | ------------------------------- | ------------------------------------------- |
@@ -199,13 +199,13 @@ 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 for input. Answer the pending approval or question, or POST a follow-up to `/eve/v1/session/:sessionId`.                                                                                                                                                 |
-| 401 on production routes                      | Expected: auth fails closed. Replace `placeholderAuth()` with your route policy. Use `vercelOidc()` only for Vercel-issued tokens; otherwise configure `httpBasic()`, JWT/OIDC helpers, or a custom `AuthFn`. 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.                                                                                                                                    |
+| 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 for input. Answer the pending approval or question, or POST a follow-up to `/eve/v1/session/:sessionId`.                                                                                                                                      |
+| 401 on production routes                      | Expected: auth fails closed. Replace `placeholderAuth()` with your route policy. Use `vercelOidc()` only for Vercel-issued tokens; otherwise configure `httpBasic()`, JWT/OIDC helpers, or a custom `AuthFn`. See [Authentication](./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
 

package/docs/guides/meta.json

@@ -6,14 +6,10 @@
     "instrumentation",
     "hooks",
     "session-context",
-    "state",
     "dynamic-capabilities",
-    "dynamic-workflows",
     "remote-agents",
     "dev-tui",
-    "acp",
     "frontend",
-    "client",
-    "ucp"
+    "client"
   ]
 }