eve 0.5.4 → 0.6.0-beta.3

package/dist/docs/public/connections.mdx

@@ -0,0 +1,196 @@
+---
+title: "Connections"
+description: "Expose external MCP and OpenAPI servers to the model: with connection tokens the model never sees."
+---
+
+A connection wires an agent into an external server you don't author: an MCP server (Linear, GitHub, a warehouse) or any HTTP API with an OpenAPI document. Eve handles the parts you'd otherwise hand-roll: it discovers the remote tools, surfaces them to the model, and brokers auth.
+
+Connections live under `agent/connections/`. The runtime name comes from the filename, so `agent/connections/linear.ts` registers as `"linear"`. The model never sees a connection's URL or credentials. It discovers tools through the built-in `connection__search` and calls them by their qualified name, `connection__<connection>__<tool>` (e.g. `connection__linear__list_issues`).
+
+## MCP connections
+
+`defineMcpClientConnection` points at an MCP server. All you have to supply is a `url` and a `description`:
+
+```ts title="agent/connections/linear.ts"
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/sse",
+  description: "Linear workspace: issues, projects, cycles, and comments.",
+  auth: {
+    getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
+  },
+});
+```
+
+The `url` must speak Streamable HTTP or SSE. Write the `description` for the model, not for yourself. It shows up in `connection__search`, and the model leans on it to decide which connection to query.
+
+### Static-token auth
+
+`getToken` returns a `TokenResult` (`{ token, expiresAt? }`), and Eve sends it as `Authorization: Bearer <token>` on every request. Because it runs on each connection attempt, you can mint a fresh token from wherever you keep secrets: an env var, a secrets manager, an internal vault, or your own OAuth exchange. If the token has a known TTL, set `expiresAt` (milliseconds since epoch) and Eve refreshes ahead of time rather than waiting for a `401`.
+
+When `getToken` is the only auth, `principalType` defaults to `"app"`: one shared credential keyed across all sessions. Switch to `principalType: "user"` when each end-user carries their own token.
+
+Eve resolves and caches connection tokens per step; they never land in conversation history or reach the model.
+
+### No auth
+
+Drop `auth` entirely for servers that need no token, like a localhost server during development or a public one:
+
+```ts
+export default defineMcpClientConnection({
+  url: "http://localhost:3001/mcp",
+  description: "Local dev server.",
+});
+```
+
+### Headers
+
+Reach for `headers` when the server wants a non-Bearer scheme (an API-key header) or some extra configuration. Headers stack on top of `auth`:
+
+```ts
+export default defineMcpClientConnection({
+  url: "https://example.com/mcp",
+  description: "Example service.",
+  headers: { "X-Api-Key": process.env.EXAMPLE_API_KEY! },
+});
+```
+
+### Tool filters
+
+To narrow which remote tools the model sees, set exactly one of `tools.allow` or `tools.block`. Filtered-out tools just don't appear in `connection__search`:
+
+```ts
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/sse",
+  description: "Linear: read-only.",
+  auth: { getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }) },
+  tools: { allow: ["search_issues", "get_issue"] },
+});
+```
+
+### Per-connection approval
+
+To put every tool a connection serves behind a human, use the helpers from `eve/tools/approval`:
+
+```ts
+import { once } from "eve/tools/approval";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/sse",
+  description: "Linear workspace.",
+  auth: { getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }) },
+  approval: once(),
+});
+```
+
+`never()` lets every call through, `once()` asks for approval the first time in a session, and `always()` asks every time. The pause and resume here is the same human-in-the-loop flow covered in [Tools](./tools).
+
+## OpenAPI connections
+
+`defineOpenAPIConnection` turns any OpenAPI 3.x document into connection tools, one per operation. Pass an HTTPS URL Eve fetches at runtime, or an inline parsed object:
+
+```ts title="agent/connections/petstore.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+  description: "Pet store inventory and orders.",
+  auth: { getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }) },
+});
+```
+
+Each operation becomes `connection__<connection>__<operationId>` (e.g. `connection__petstore__getInventory`). When an operation has no `operationId`, Eve derives a deterministic `<method>_<sanitized-path>` name instead.
+
+`auth`, `headers`, and `approval` work exactly as they do for MCP. There are two fields specific to OpenAPI:
+
+| Field        | Purpose                                                                                                                 |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `baseUrl`    | Base URL operation paths resolve against. Optional; defaults to the document's first usable `servers` entry.            |
+| `operations` | Filter keyed on `operationId` (`allow` or `block`). Mirrors `tools` on MCP connections, but names operations not tools. |
+
+## Interactive OAuth via Vercel Connect
+
+When the server uses OAuth and you want each end-user to sign in through their own browser, turn on interactive authorization with [Vercel Connect](https://vercel.com/docs/connect). The `connect()` helper from `@vercel/connect/eve` handles consent, encrypted token storage, and refresh, then hooks all of that into Eve's authorization flow:
+
+```ts title="agent/connections/linear.ts"
+import { connect } from "@vercel/connect/eve";
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/sse",
+  description: "Linear workspace: issues, projects, cycles, and comments.",
+  auth: connect("linear"),
+});
+```
+
+`"linear"` is the UID you chose when registering the Connect client. Connect-managed OAuth is user-scoped by default, so the runtime resolves the per-user token before each tool call. The full setup (Connect client provisioning, project linking, the runtime consent flow) lives in [Auth & route protection](./advanced/auth-and-route-protection).
+
+## Self-hosted interactive OAuth
+
+Running your own OAuth? Use `defineInteractiveAuthorization` from `eve/connections`, which takes a three-method form. Eve mints a callback URL, parks the turn on a framework-owned webhook, and resumes once the token comes back. No Vercel Connect required. Interactive auth is always `principalType: "user"`, and the factory pins that for you.
+
+```ts title="agent/connections/linear.ts"
+import {
+  ConnectionAuthorizationRequiredError,
+  defineInteractiveAuthorization,
+  defineMcpClientConnection,
+} from "eve/connections";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/sse",
+  description: "Linear workspace.",
+  auth: defineInteractiveAuthorization<{ verifier: string }>({
+    // Probed before every tool call. Return a token to run the tool;
+    // throw `Required` to start the consent flow.
+    getToken: async ({ principal }) => {
+      const token = await lookupCachedToken(principal);
+      if (!token) throw new ConnectionAuthorizationRequiredError("linear");
+      return { token };
+    },
+    // Runs in a durable step. Return the user-facing `challenge` and
+    // an optional `resume` value the runtime journals across the park.
+    startAuthorization: async ({ callbackUrl }) => {
+      const verifier = makePkceVerifier();
+      return {
+        challenge: { url: buildAuthorizeUrl(callbackUrl, verifier) },
+        resume: { verifier },
+      };
+    },
+    // Runs when the provider redirects to the callback URL. `resume` is
+    // typed as `{ verifier: string } | undefined`; `callback.params`
+    // holds the IdP's returned query/body params.
+    completeAuthorization: async ({ resume, callback }) => {
+      const token = await exchangeCode(resume!.verifier, callback.params.code!);
+      return { token };
+    },
+  }),
+});
+```
+
+`getToken` runs before every tool call. `startAuthorization` and `completeAuthorization` are both-or-neither: provide one without the other and you get a definition error. The `challenge` rides along verbatim on the `authorization.required` event. Set `url` for redirect/device flows, `userCode` for a device code, and `instructions` as the call to action when there's no URL. Drop `resume` when the provider keeps flow state server-side, so nothing has to cross the step boundary.
+
+### Signaling authorization state
+
+Two error classes drive the consent flow. Throw them from `getToken` or `completeAuthorization`; both are exported from `eve/connections`.
+
+- `ConnectionAuthorizationRequiredError(connectionName)`: the user must authorize. Throw it from `getToken` to emit `authorization.required` and kick off the flow.
+- `ConnectionAuthorizationFailedError(connectionName, { reason?, retryable? })`: authorization failed. `reason` is a stable machine-readable code (e.g. `"access_denied"`) that shows up on the `authorization.completed` event and the failed tool result. `retryable` defaults to `true`; set it to `false` for terminal cases like user denial so the runtime stops re-prompting.
+
+```ts
+import { ConnectionAuthorizationFailedError } from "eve/connections";
+
+throw new ConnectionAuthorizationFailedError("linear", {
+  reason: "access_denied",
+  retryable: false,
+});
+```
+
+To narrow a caught error, use `isConnectionAuthorizationRequiredError(err)` and `isConnectionAuthorizationFailedError(err)`. They match on `err.name`, which is why they survive the class-identity split `instanceof` can hit after bundling.
+
+## What to read next
+
+- [Integrations](/integrations): browse every channel and connection Eve ships, in one gallery.
+- [Tools](./tools): authored tools live alongside connection-provided tools; the same approval helpers apply.
+- [Auth & route protection](./advanced/auth-and-route-protection): the full interactive-OAuth flow with Vercel Connect.
+- [Security model](./advanced/security-model): how connection credentials stay out of the model's reach.

package/dist/docs/public/frontend/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Frontend",
+  "pages": ["overview", "nextjs", "nuxt", "sveltekit", "use-eve-agent-vue", "use-eve-agent-svelte"]
+}

package/dist/docs/public/frontend/nextjs.mdx

@@ -0,0 +1,79 @@
+---
+title: "Next.js"
+description: "Run an Eve agent and a Next.js app as one project with withEve."
+---
+
+`eve/next` lets you ship a Next.js frontend and an Eve agent as a single project. Wrap your config with `withEve()` and the two run together: one dev server, one Vercel deploy. [`useEveAgent`](./overview) finds the mounted routes on its own, so there's no CORS to fight and no URL env vars to keep in sync.
+
+## Wrap the Next.js config
+
+```ts title="next.config.ts"
+import type { NextConfig } from "next";
+import { withEve } from "eve/next";
+
+const nextConfig: NextConfig = {};
+
+export default withEve(nextConfig);
+```
+
+By default `withEve()` looks for an `agent/` folder next to your Next.js project root. If the agent lives somewhere else, point at it with `eveRoot`:
+
+```ts
+export default withEve(nextConfig, {
+  eveRoot: "../my-agent",
+});
+```
+
+### `withEve` options
+
+All fields are optional.
+
+| Option                  | Type      | Default                | Purpose                                                                                                                                                 |
+| ----------------------- | --------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eveRoot`               | `string`  | Next.js app root       | Path to the Eve app root, relative to `process.cwd()` unless absolute. Set it when the agent lives outside the Next.js project.                         |
+| `eveBuildCommand`       | `string`  | `"eve build"`          | Build command for the generated Eve Vercel service. Use it when the Eve service needs project-specific prework, without changing the Next.js build.     |
+| `configureVercelOutput` | `boolean` | `true`                 | Set to `false` to skip creating or updating `.vercel/output/config.json`. By default `withEve` writes the `experimentalServices` entries for both apps. |
+| `servicePrefix`         | `string`  | `"/_eve_internal/eve"` | Private Vercel route namespace for the Eve service. Must match the Eve service's mount in your Vercel Build Output config when you set it manually.     |
+
+## Call the hook
+
+With `withEve()` in `next.config.ts`, the Eve routes are same-origin, so client code can call [`useEveAgent`](./overview) without naming a host. Cookie-based auth just works, whether that's Auth.js or any session cookie, since the browser already sends those cookies on every Eve request. For non-cookie schemes, attach the credentials yourself:
+
+```tsx
+const agent = useEveAgent({
+  headers: async () => ({
+    authorization: `Bearer ${await getAccessToken()}`,
+  }),
+});
+```
+
+Before deploying a user-facing app, add `agent/channels/eve.ts` so production requests run your app's auth policy. See [Channels](../channels/overview) and [Auth & route protection](../advanced/auth-and-route-protection).
+
+## Dev vs deploy topology
+
+- **Local dev.** `pnpm dev` boots the Eve dev server next to `next dev` and rewrites the Eve routes over to it. The browser only ever talks to the Next.js origin.
+- **Vercel.** The web app and the Eve runtime deploy as a single project. The web app stays public; the Eve runtime sits behind it on the same site origin. When the agent needs its own build step, set `eveBuildCommand`:
+
+  ```ts
+  export default withEve(nextConfig, {
+    eveBuildCommand: "pnpm build:eve",
+  });
+  ```
+
+- **Local production build.** `next build && next start` proxies Eve routes to `http://127.0.0.1:4274`. Change the port with `EVE_NEXT_PRODUCTION_PORT`:
+
+  ```bash
+  EVE_NEXT_PRODUCTION_PORT=5000 pnpm build && pnpm start
+  ```
+
+- **Non-Vercel hosts.** If the Eve service lives on a separate origin, tell Next.js where to find it with `EVE_NEXT_PRODUCTION_ORIGIN`:
+
+  ```bash
+  EVE_NEXT_PRODUCTION_ORIGIN=https://agent.example.com pnpm build
+  ```
+
+## What to read next
+
+- [Frontend overview](./overview): the `useEveAgent` API
+- [Auth & route protection](../advanced/auth-and-route-protection)
+- [Deployment](../advanced/deployment)

package/dist/docs/public/frontend/nuxt.mdx

@@ -0,0 +1,82 @@
+---
+title: "Nuxt"
+description: "Run an Eve agent and a Nuxt app as one project with the eve/nuxt module."
+---
+
+The `eve/nuxt` module folds a Nuxt frontend and an Eve agent into a single project: one dev server, one Vercel deploy. The auto-imported [`useEveAgent`](./use-eve-agent-vue) composable finds the mounted routes on its own, so you skip the usual CORS headaches and URL env vars.
+
+## Register the module
+
+```ts title="nuxt.config.ts"
+export default defineNuxtConfig({
+  modules: ["eve/nuxt"],
+});
+```
+
+The module looks for an `agent/` folder in the Nuxt project root. Pass `eveRoot` when the agent lives elsewhere:
+
+```ts
+export default defineNuxtConfig({
+  modules: ["eve/nuxt"],
+  eve: {
+    eveRoot: "../my-agent",
+  },
+});
+```
+
+## Call the composable
+
+`useEveAgent` (`eve/vue`) is auto-imported, so a component can call it without an explicit import and without naming a host:
+
+```vue
+<script setup lang="ts">
+const { status, send } = useEveAgent();
+
+const isBusy = computed(() => status.value === "submitted" || status.value === "streaming");
+
+const message = ref("");
+
+async function handleSubmit() {
+  const text = message.value.trim();
+  if (!text || isBusy.value) return;
+  message.value = "";
+  await send({ message: text });
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <input v-model="message" :disabled="isBusy" />
+    <button type="submit" :disabled="isBusy">Send</button>
+  </form>
+</template>
+```
+
+Out of the box the module gives Eve a framework default channel. When you want to pick the route auth policy yourself, add `agent/channels/eve.ts` and swap `none()` for a helper like `vercelOidc()` on protected apps. See [Channels](../channels/overview) and [Auth & route protection](../advanced/auth-and-route-protection).
+
+## Dev vs deploy topology
+
+- **Local dev.** `pnpm dev` starts the Eve dev server next to `nuxt dev` and proxies the Eve routes through it. As far as the browser knows, everything is the Nuxt origin.
+- **Vercel.** A single Vercel project carries both the Nuxt app and the Eve runtime. The web app stays public; the runtime sits behind it on the same origin. Set `eveBuildCommand` when the agent needs its own build step:
+
+  ```ts
+  export default defineNuxtConfig({
+    modules: ["eve/nuxt"],
+    eve: {
+      eveBuildCommand: "pnpm build:eve",
+    },
+  });
+  ```
+
+- **Non-Vercel hosts.** Point Nuxt at a separate Eve origin with `EVE_NUXT_PRODUCTION_ORIGIN`. To override the local port (it defaults to `4274`), use `EVE_NUXT_PRODUCTION_PORT`:
+
+  ```bash
+  EVE_NUXT_PRODUCTION_ORIGIN=https://agent.example.com pnpm build
+  EVE_NUXT_PRODUCTION_PORT=5000 pnpm build && pnpm preview
+  ```
+
+## What to read next
+
+- [`useEveAgent` (Vue)](./use-eve-agent-vue): the composable API
+- [Auth & route protection](../advanced/auth-and-route-protection)
+- [Deployment](../advanced/deployment)

package/dist/docs/public/frontend/overview.mdx

@@ -0,0 +1,234 @@
+---
+title: "Overview"
+description: "Put an Eve agent behind a browser chat UI with useEveAgent."
+---
+
+The frontend helpers put a browser chat or agent UI on top of an Eve agent. `useEveAgent()` does the heavy lifting: it opens a durable session, sends turns, streams the reply back, and turns the raw event stream into render-ready state. React is the reference implementation, and [Vue](./use-eve-agent-vue) and [Svelte](./use-eve-agent-svelte) ship the same surface.
+
+## The integration model
+
+A browser UI is just a client of the agent's HTTP routes (the [Eve channel](../channels/overview)). Two layers wire it up:
+
+- **The framework integration** mounts the Eve routes on your app's origin, so the browser never crosses a CORS boundary or reads an env var to find the agent. Pick yours: [Next.js](./nextjs) (`withEve`), [Nuxt](./nuxt) (the `eve/nuxt` module), or [SvelteKit](./sveltekit) (the `eveSvelteKit` Vite plugin). On any other stack the hook talks to same-origin `/eve/v1/*` routes directly, or you pass an explicit `host`.
+- **The hook** (`useEveAgent`) holds the session state, streaming, errors, and composer status. It defaults to same-origin Eve routes such as `/eve/v1/session`.
+
+For a guided setup, the [Guides](/docs/skills/eve-add-next) walk through the wiring step by step: [add a Next.js frontend to an existing Eve agent](/docs/skills/eve-add-next), or [add Eve to an existing Next.js app](/docs/skills/eve-add-agent).
+
+For scripts, server-to-server calls, evals, tests, or custom clients that do not need framework UI state, use the [TypeScript Client](../client/overview) directly.
+
+## Basic chat (React)
+
+The hook lives in `eve/react`. Render `data.messages`, gate the composer on `status`, and send text with `send`. That's the whole loop:
+
+```tsx
+"use client";
+
+import { useEveAgent } from "eve/react";
+
+export function Chat() {
+  const agent = useEveAgent();
+  const isBusy = agent.status === "submitted" || agent.status === "streaming";
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        const form = new FormData(event.currentTarget);
+        const message = String(form.get("message") ?? "").trim();
+        if (message.length > 0) {
+          void agent.send({ message });
+        }
+      }}
+    >
+      {agent.data.messages.map((message) => (
+        <article key={message.id}>
+          <header>{message.role}</header>
+          {message.parts.map((part, index) =>
+            part.type === "text" ? <p key={index}>{part.text}</p> : null,
+          )}
+        </article>
+      ))}
+      <input name="message" disabled={isBusy} />
+      <button disabled={isBusy} type="submit">
+        Send
+      </button>
+    </form>
+  );
+}
+```
+
+## Returned state
+
+`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 session cursor (`sessionId`, `continuationToken`, `streamIndex`). |
+| `send`    | Send text or the full turn payload (multi-part messages, HITL responses).      |
+| `stop`    | Abort the active request.                                                      |
+| `reset`   | Clear local events, data, errors, and the local session cursor.                |
+
+Most chat UIs only need `data.messages` and `status`. Drop down to `events` when you want to render lower-level activity (tool calls, reasoning deltas) that the default reducer doesn’t surface.
+
+`data.messages` are `EveMessage[]` following the AI SDK `UIMessage` convention, so they drop straight into any AI SDK UI primitive that accepts a `UIMessage[]`. Parts include user text, assistant text, reasoning, tool calls, tool results, and input requests.
+
+## Sending and streaming
+
+Pass an object to `send()` for text, multi-part messages, attachments, HITL responses, and per-turn context:
+
+```tsx
+await agent.send({ message: "Summarize this session." });
+
+await agent.send({
+  message: [
+    { type: "text", text: "What is in this file?" },
+    {
+      type: "file",
+      data: fileDataUrl, // base64 data URL
+      mediaType: "application/pdf",
+      filename: "report.pdf",
+    },
+  ],
+});
+```
+
+Assistant text, reasoning, tool calls, and tool results stream into `data` as they arrive, and `status` moves from `ready` to `submitted` to `streaming` and back. Call `stop()` to abort the active request. Call `reset()` to clear local state so the next send starts a fresh durable session.
+
+## Human-in-the-loop prompts
+
+Tools opt into approval with `needsApproval` on the [server side](../tools), and the model can also ask a question with `ask_question`. Either way the stream emits an `input.requested` event, and the pending request rides on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `send()`:
+
+```tsx
+const request = agent.data.messages
+  .at(-1)
+  ?.parts.find((part) => part.type === "dynamic-tool" && part.toolMetadata?.eve?.inputRequest)
+  ?.toolMetadata?.eve?.inputRequest;
+
+if (request) {
+  await agent.send({
+    inputResponses: [{ requestId: request.requestId, optionId: "approve" }],
+  });
+}
+```
+
+`request.prompt` and `request.options` give you what you need to render the approve and deny UI. The default reducer marks the part as responded right away, then updates it again once Eve streams the resumed result.
+
+## Attach page context per turn
+
+`clientContext` adds ephemeral context for the next model call and nothing more. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, so it never dispatches a turn on its own and never lands in durable session history. Pass it directly to `send()`:
+
+```tsx
+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, use `prepareSend`. It runs right before each send and returns the (possibly augmented) turn:
+
+```tsx
+const agent = useEveAgent({
+  prepareSend: (input) => ({
+    ...input,
+    clientContext: { route: location.pathname },
+  }),
+});
+```
+
+## Lifecycle callbacks
+
+On top of `onSessionChange`, the hook 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 `{ data, status, session, ... }` snapshot once a turn settles.
+
+```tsx
+const agent = useEveAgent({
+  onEvent: (event) => console.debug(event.type),
+  onError: (error) => toast.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`). When you want `data` shaped differently, pass a `reducer` implementing `EveAgentReducer<TData>`:
+
+```tsx
+import { useEveAgent } from "eve/react";
+import type { EveAgentReducer } from "eve/react";
+
+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, just return `data` unchanged for them.
+
+## Resumable sessions
+
+The browser conversation lives durably on the server. Persist the `session` cursor and you can pick it back up after a reload:
+
+```tsx
+const [initialSession] = useState(() => {
+  const raw = localStorage.getItem("eve-session");
+  return raw ? JSON.parse(raw) : undefined;
+});
+
+const agent = useEveAgent({
+  initialSession,
+  onSessionChange(session) {
+    localStorage.setItem("eve-session", JSON.stringify(session));
+  },
+});
+```
+
+Store the full `session` object (`sessionId`, `continuationToken`, `streamIndex`), not a single field.
+
+## Custom hosts and headers
+
+Pass `host` when the Eve server isn't same-origin, and pass `auth` or `headers` when the channel needs credentials. Function values are re-resolved before every HTTP request, reconnects included:
+
+```tsx
+const agent = useEveAgent({
+  host: "https://agent.example.com",
+  auth: {
+    bearer: async () => await getAccessToken(),
+  },
+});
+```
+
+## Per-framework integration
+
+| Framework | Integration                          | Hook                                             |
+| --------- | ------------------------------------ | ------------------------------------------------ |
+| Next.js   | [`withEve`](./nextjs)                | [`useEveAgent` (React)](#basic-chat-react)       |
+| Nuxt      | [`eve/nuxt` module](./nuxt)          | [`useEveAgent` (Vue)](./use-eve-agent-vue)       |
+| SvelteKit | [`eveSvelteKit` plugin](./sveltekit) | [`useEveAgent` (Svelte)](./use-eve-agent-svelte) |
+| Any React | same-origin or `host`                | [`useEveAgent` (React)](#basic-chat-react)       |
+
+## What to read next
+
+- [Sessions, runs & streaming](../advanced/sessions-runs-and-streaming): the event stream and session cursor
+- [Channels](../channels/overview): the HTTP routes the hook talks to
+- [TypeScript Client](../client/overview): the lower-level client underneath the frontend hooks
+- [Guides](/docs/skills/eve-add-next): step-by-step guides for wiring Eve into Next.js