diff --git a/.changeset/ai-harness-transport.md b/.changeset/ai-harness-transport.md
new file mode 100644
index 0000000000..9f0d8ebd40
--- /dev/null
+++ b/.changeset/ai-harness-transport.md
@@ -0,0 +1,11 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+Serve a harness session to clients.
+
+- `createHarnessHandler()` serves a session over HTTP. `POST run` is standard AG-UI, so `useChat` with `fetchServerSentEvents` works on a harness, with approvals, client tools, and a reload that joins the running turn. `POST control`, `GET events`, `GET transcript`, `GET agent-transcript` (the messages of a child agent run), `GET snapshot`, `GET describe`, `sessions`, and the media routes cover the rest.
+- `handleHarnessSocket()` serves the same session over a WebSocket.
+- `expose` on `defineHarness()` names the agents, settings, config keys, and commands that a client can use. Any other input of those kinds gets `rejected` with `not_exposed`.
+- `createHarnessClient()` from `@tanstack/ai-harness/client` is a typed, browser-safe client. It sends inputs, reads the session, and streams events that resume from a cursor.
+- `oauthConnector()` and the OAuth helpers (`loopbackLogin`, `deviceLogin`, `exchangeCode`, `refreshCredential`, and more) keep a credential per sender. `token({ wait: true })` stops the turn with an `auth_required` interrupt until the user signs in.
diff --git a/.changeset/ai-harness-view.md b/.changeset/ai-harness-view.md
new file mode 100644
index 0000000000..303679dbe7
--- /dev/null
+++ b/.changeset/ai-harness-view.md
@@ -0,0 +1,10 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+Add `createSessionView()` in `@tanstack/ai-harness/view`. It turns a session (local, or remote through `createHarnessClient()`) into one live TanStack Store state that works with any UI library.
+
+- The state: messages with their parts, tool calls, approvals, client tools, other interrupts, questions, sign-ins, child agents with their results, media with signed URLs, waiting inputs, usage, models, settings, commands, and plugin state.
+- Actions: `send` (a prompt, a steer, or a `/command`), `followUp`, `continue`, `upload`, `cancel`, `cancelInput`, `setDelivery`, `configure`, `reset`, `revert`, and the answers to approvals (with edited arguments), client tools, interrupts, and questions.
+- Typed events: `view.on('approval' | 'interrupt' | 'turnEnd' | ..., handler)` and plugin events.
+- A view that opens while a turn runs shows the turn from its start. After a reload, each child agent shows its own messages again.
diff --git a/.changeset/ai-mcp-harness.md b/.changeset/ai-mcp-harness.md
new file mode 100644
index 0000000000..e3f5f39956
--- /dev/null
+++ b/.changeset/ai-mcp-harness.md
@@ -0,0 +1,12 @@
+---
+'@tanstack/ai-mcp': minor
+---
+
+Use MCP in a TanStack AI harness.
+
+- `@tanstack/ai-mcp/harness` adds `createHarnessMcpServer`. It serves a harness as an MCP server, so Claude Code, Claude Desktop, Cursor, or another agent can use it. The tools are `chat`, `steer`, `cancel`, `approve`, `reject`, `resolve`, `answer`, and `status`, plus `agent_<name>` for each exposed agent and `command_<name>` for each exposed command. Every tool takes an optional `threadId`. With `approvals: 'ask'` (the default), the client asks the user about each approval when it supports elicitation. Otherwise the approvals come back in the result. `approvals: 'auto'` approves every tool call. `resolve` answers every kind of interrupt in one call.
+- `@tanstack/ai-mcp/harness` also adds the `mcp()` harness plugin. It connects stdio and HTTP servers by name, gives the model their tools as `<server>_<tool>`, and adds a `/mcp` status command. `oauth: true` signs in to a server with `/connect <name>`.
+- `@tanstack/ai-mcp/connector` adds `mcpConnector`: one OAuth MCP server as a harness plugin, with `needsApproval`, `prefix`, `scopes`, and `clientName`. The sign-in passes the `iss` of the callback on (RFC 9207).
+- `mcp()` and `mcpConnector` answer the `elicitation/create` requests of MCP spec 2025 servers, and the input requests of spec 2026-07-28 servers, as session questions. One tool call can ask up to 5 times.
+
+`@tanstack/ai-harness` is an optional peer dependency. Only the `./harness` and `./connector` entries need it.
diff --git a/.changeset/harness-join-any-instance.md b/.changeset/harness-join-any-instance.md
new file mode 100644
index 0000000000..d7089c0ae3
--- /dev/null
+++ b/.changeset/harness-join-any-instance.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-harness': patch
+---
+
+On a durable host (`stores.log` and `stores.runs`), any server instance can serve a run.
+
+- `POST run` sends the log cursor of each event as its SSE `id`. A client that is cut off sends the same request with `Last-Event-ID`, and any instance continues the stream from there. The turn does not run again.
+- `GET run?runId=` finds a turn that another instance runs. It streams the turn from the shared log, from its start or from `Last-Event-ID`, until the turn ends.
+- `GET run?threadId=` shows a turn that another instance runs as `activeRun`, so a reloaded `useChat` joins it.
diff --git a/.changeset/harness-secure-defaults.md b/.changeset/harness-secure-defaults.md
new file mode 100644
index 0000000000..d8f7ec8847
--- /dev/null
+++ b/.changeset/harness-secure-defaults.md
@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-harness': patch
+---
+
+Make the transport defaults safe for a server with many instances.
+
+- `createHarnessHandler` and `handleHarnessSocket` need `canAccess`. To let every principal use every thread, pass `canAccess: () => true`.
+- On a durable host (`stores.log`), `createHarnessHandler` throws without `mediaSecret`, so a media URL that one instance signs works on every instance.
+- `oauthConnector` needs `login`. Use `'device'` on a server, and `'loopback'` only for a harness on the user's own machine, such as a CLI.
diff --git a/.changeset/harness-view-experimental.md b/.changeset/harness-view-experimental.md
new file mode 100644
index 0000000000..cdb14f7fa5
--- /dev/null
+++ b/.changeset/harness-view-experimental.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-harness': patch
+---
+
+Mark `createSessionView`, `SessionViewState`, and `SessionViewEvents` as `@experimental`. Document that event cursors are opaque strings: log positions on a durable host, and process-local counters without a log store.
diff --git a/docs/config.json b/docs/config.json
index 111ac54010..3090110a65 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -935,6 +935,18 @@
           "addedAt": "2026-10-13",
           "updatedAt": "2026-10-14"
         },
+        {
+          "label": "Connect clients",
+          "to": "harness/connect",
+          "addedAt": "2026-10-13",
+          "updatedAt": "2026-10-14"
+        },
+        {
+          "label": "Send inputs safely",
+          "to": "harness/inputs",
+          "addedAt": "2026-10-13",
+          "updatedAt": "2026-10-14"
+        },
         {
           "label": "Durable sessions",
           "to": "harness/durable-sessions",
@@ -994,6 +1006,24 @@
           "addedAt": "2026-10-13",
           "updatedAt": "2026-10-14"
         },
+        {
+          "label": "Auth and connectors",
+          "to": "harness/auth",
+          "addedAt": "2026-10-13",
+          "updatedAt": "2026-10-14"
+        },
+        {
+          "label": "Share a thread between people",
+          "to": "harness/shared-threads",
+          "addedAt": "2026-10-13",
+          "updatedAt": "2026-10-14"
+        },
+        {
+          "label": "Build your own UI",
+          "to": "harness/custom-ui",
+          "addedAt": "2026-10-13",
+          "updatedAt": "2026-10-14"
+        },
         {
           "label": "Run agents from a harness",
           "to": "harness/subagents",
@@ -1005,6 +1035,17 @@
           "to": "harness/skills",
           "addedAt": "2026-10-13"
         },
+        {
+          "label": "Use MCP servers",
+          "to": "harness/mcp",
+          "addedAt": "2026-10-13",
+          "updatedAt": "2026-10-14"
+        },
+        {
+          "label": "Use from any MCP client",
+          "to": "harness/mcp-server",
+          "addedAt": "2026-10-13"
+        },
         {
           "label": "Use a harness from an editor (ACP)",
           "to": "harness/acp",
diff --git a/docs/harness/auth.md b/docs/harness/auth.md
new file mode 100644
index 0000000000..d825439b85
--- /dev/null
+++ b/docs/harness/auth.md
@@ -0,0 +1,177 @@
+---
+title: Auth and connectors
+id: harness-auth
+order: 7
+description: "Let users sign in to GitHub and other OAuth services from the harness. Tokens stay in your credential store and never reach the model."
+keywords:
+  - tanstack ai
+  - harness
+  - oauth
+  - connectors
+  - credentials
+---
+
+Your agent needs to open a pull request, so it needs the user's GitHub token. The user should sign in once, in the browser, and the model should never see the token. `oauthConnector` does that: it adds `/connect github`, stores the token, and hands it to your tools.
+
+## 1. Add a connector
+
+```ts group=harness-auth
+import { toolDefinition } from '@tanstack/ai'
+import { defineHarness, oauthConnector } from '@tanstack/ai-harness'
+import { openaiText } from '@tanstack/ai-openai'
+
+const github = oauthConnector({
+  id: 'github',
+  label: 'GitHub',
+  // The harness runs on the user's machine (a CLI), so open a browser here.
+  login: 'loopback',
+  oauth: {
+    authorizationUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    deviceUrl: 'https://github.com/login/device/code',
+    clientId: 'your-github-oauth-app-client-id',
+    scopes: ['repo'],
+  },
+  tools: (token) => [
+    toolDefinition({ name: 'list_issues', description: 'List my open issues' }).server(
+      async () => {
+        const response = await fetch('https://api.github.com/issues', {
+          headers: { authorization: `Bearer ${await token()}` },
+        })
+        return response.json()
+      },
+    ),
+  ],
+})
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-6.1-sol'),
+  plugins: () => [github],
+})
+```
+
+`token()` returns a fresh access token. It refreshes an expired token when the service gave a refresh token.
+
+## 2. Sign in
+
+- The user runs `/connect github`.
+- With `login: 'loopback'`, the CLI opens the browser. The harness listens on `127.0.0.1` on a random port for one callback, with PKCE and a random `state`.
+- The token goes into the credential store. `/disconnect github` deletes it.
+
+`login` is required. Use `login: 'device'` for a harness on a server, and for SSH sessions, containers, and CI. The user then gets a code to enter on the service's page. Device login needs `oauth.deviceUrl`.
+
+If a tool runs before sign-in, it stops with a `harness.auth_required` event. The CLI shows which service to connect.
+
+## Wait for the sign-in
+
+A turn from a background agent or an email runs while nobody watches it. That turn can need a sign-in. Without a sign-in, the tool fails, and the work of that turn stops. Pass `wait: true` to `token()`. Then the turn waits for the sign-in and continues after it.
+
+```ts group=harness-auth-wait
+import { toolDefinition } from '@tanstack/ai'
+import { defineHarness, oauthConnector } from '@tanstack/ai-harness'
+import { openaiText } from '@tanstack/ai-openai'
+
+const github = oauthConnector({
+  id: 'github',
+  label: 'GitHub',
+  // The server cannot open a browser for the user, so show a code.
+  login: 'device',
+  oauth: {
+    authorizationUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    deviceUrl: 'https://github.com/login/device/code',
+    clientId: 'your-github-oauth-app-client-id',
+    scopes: ['repo'],
+  },
+  tools: (token) => [
+    toolDefinition({ name: 'list_issues', description: 'List my open issues' }).server(
+      async () => {
+        const response = await fetch('https://api.github.com/issues', {
+          headers: { authorization: `Bearer ${await token({ wait: true })}` },
+        })
+        return response.json()
+      },
+    ),
+  ],
+})
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-6.1-sol'),
+  plugins: () => [github],
+  // A web app starts the sign-in with this command.
+  expose: { commands: ['connect:github'] },
+})
+```
+
+In your own plugin, use `ctx.credentials.require('github', { wait: true })`.
+
+When the credential is missing, the turn stops with an interrupt:
+
+- The interrupt has `reason: 'auth_required'`. Its `metadata['tanstack:interruptPayload'].request.connector` is `'github'`.
+- The sign-in belongs to the sender of the stopped turn. When that person saves the credential, the same turn continues as that person, and the tool runs again. The save can be `/connect github`, the `connect:github` command, or `ctx.credentials.set`.
+- A credential that another person saves never continues the turn.
+- To stop the wait, resolve the interrupt with `status: 'cancelled'`. Then the tool fails, the same as without `wait`.
+- On a durable host, the wait continues after a restart.
+- `wait` is for a tool of the running chat turn. Do not pass it in a command, a background agent, or a hook. The credentials of a command never wait.
+- Provider keys (`ctx.keys.require`) do not wait.
+
+In a web app, the wait shows in `state.signIns` of the session view, also after a reload. When the user presses your connect button, run the connector command. Each sign-in then has the `url` and the `userCode` to show. A client can run only the commands in `expose.commands`, so the harness above exposes `connect:github` (see [Choose what clients can change](./connect#choose-what-clients-can-change)):
+
+```ts group=harness-auth-wait-client
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import { createSessionView } from '@tanstack/ai-harness/view'
+
+const view = createSessionView(
+  createHarnessClient({ url: '/api/harness', threadId: 'user-1-thread' }),
+)
+
+view.on('signIn', (signIn) => {
+  console.log(`Connect ${signIn.connector} to continue the turn.`)
+})
+
+export const connectGithub = () => view.command('connect:github')
+```
+
+After the sign-in, the turn finishes its work with no new message.
+
+## Keep credentials
+
+The host reads credentials from `stores.credentials`, keyed by the sender of the running turn. Without it, credentials live in memory until the process stops. When several people write in one thread, see [Share a thread between people](./shared-threads).
+
+```ts group=harness-auth
+import { defineCredentialStore } from '@tanstack/ai-persistence'
+import type { Credential } from '@tanstack/ai-persistence'
+
+const saved = new Map<string, Credential>()
+const keyOf = (userId: string | undefined, id: string) => `${userId ?? 'tenant'}:${id}`
+
+export const credentials = defineCredentialStore({
+  get: async ({ scope, id }) => saved.get(keyOf(scope.userId, id)) ?? null,
+  set: async ({ scope, id, credential }) => {
+    saved.set(keyOf(scope.userId, id), credential)
+  },
+  delete: async ({ scope, id }) => {
+    saved.delete(keyOf(scope.userId, id))
+  },
+  list: async (scope) =>
+    [...saved.entries()]
+      .filter(([key]) => key.startsWith(`${scope.userId ?? 'tenant'}:`))
+      .map(([key, credential]) => ({ id: key.split(':')[1] ?? key, type: credential.type })),
+})
+```
+
+- Encrypt tokens at rest in a real store.
+- `list` returns ids and types only, never the secret values.
+- A credential saved without a `userId` belongs to the whole tenant. A user who has no credential of their own uses it. See [Share one credential with the whole organization](./shared-threads#share-one-credential-with-the-whole-organization).
+
+## Read credentials in your own plugin
+
+`ctx.credentials.require('github')` returns the credential, or stops with `auth_required` when the user has not signed in. Plugins read only the credentials of the sender of the running turn. Outside a turn, they read the credentials of the person who opened the session.
+
+## What you have now
+
+- Browser and device-code sign-in for any OAuth service.
+- Tools that get a fresh token without the model seeing it.
+- Turns that wait for a sign-in and then finish their work.
diff --git a/docs/harness/connect.md b/docs/harness/connect.md
new file mode 100644
index 0000000000..dfd4fe46ba
--- /dev/null
+++ b/docs/harness/connect.md
@@ -0,0 +1,359 @@
+---
+title: Connect clients to a harness
+id: harness-connect
+order: 2
+description: "Serve a harness session over HTTP, SSE, or WebSocket. Talk to it from a web app or another chat() call."
+keywords:
+  - tanstack ai
+  - harness
+  - AG-UI
+  - websocket
+  - harnessText
+---
+
+Your harness runs on a server, but the people who use it are in a browser or another agent. `createHarnessHandler` serves a session over HTTP. A web app talks to it with `createHarnessClient`, and another `chat()` call with `harnessText`.
+
+## Serve the session over HTTP
+
+Mount one fetch handler on a route. `authorize` is required, so no endpoint is open by accident.
+
+```ts group=harness-connect
+import { defineHarness, createHarnessHandler, createHarnessHost } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-6.1-sol'),
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+
+export const handler = createHarnessHandler({
+  host,
+  harness: assistant,
+  authorize: (request) =>
+    request.headers.get('authorization') === `Bearer ${process.env.HARNESS_TOKEN}`
+      ? { id: 'user-1' }
+      : null,
+  canAccess: (principal, threadId) => threadId.startsWith(`${principal.id}-`),
+})
+```
+
+`canAccess` is required. It decides which threads each principal can use. To let every principal use every thread, pass `canAccess: () => true`.
+
+On a durable host (`stores.log`), also set `mediaSecret`. It signs media URLs, so every instance must use the same value. Without a log store, the default is a random key, and signed URLs stop working after a restart.
+
+The handler answers these paths under your route:
+
+- `GET capabilities`: the AG-UI capabilities, with the agents in `expose.agents`.
+- `POST run`: standard AG-UI. One request runs one prompt and streams it as SSE. The prompt keeps every content part of the last user message, for example an image. `useChat` works with it. See [Use it from useChat](#use-it-from-usechat).
+- `GET run?threadId=`: the saved messages, the running turn, and the waiting approvals, for a `useChat` that loads the thread after a reload.
+- `GET run?runId=`: the turn with that run id as SSE, from its first event. A reloaded `useChat` joins a running turn with it.
+- `GET events?threadId=`: every event of the session as SSE. Each event id is a cursor, so a reconnect with `Last-Event-ID` continues where it stopped.
+- `POST control`: send `{ threadId, input }`, for example `{ op: 'prompt', message }`. You get a receipt back. Agents, settings, config keys, and commands need `expose`. See [Choose what clients can change](#choose-what-clients-can-change).
+- `GET snapshot?threadId=`: the status, running operations, and waiting approvals.
+- `GET agent-transcript?threadId=&subagentRunId=`: the saved messages of one child agent of the thread. See [Show what a child wrote after a reload](./subagents#show-what-a-child-wrote-after-a-reload).
+
+## Cursors
+
+Each event id of `GET events` and `GET run`, and the `cursor` of each `harness.event` frame, is an opaque string. Send it back as `Last-Event-ID` or `from`, as it is. Do not parse it.
+
+- On a durable host (`stores.log`), a cursor is a position in the log of the thread. It works on every instance and after a restart.
+- Without a log store, a cursor is a counter in the memory of one process. Another instance or a restart does not know it.
+
+To run more than one instance behind one URL, use `stores.log`.
+
+## Choose what clients can change
+
+A client can send a prompt and answer questions. Other inputs can change how the session works, so a client can use only what the harness exposes. Nothing is exposed by default.
+
+Name what a client can use in `expose`:
+
+```ts group=harness-connect
+export const team = defineHarness({
+  name: 'acme/team-assistant',
+  adapter: openaiText('gpt-6.1-sol'),
+  expose: { settings: ['instructions'], commands: ['undo'] },
+})
+```
+
+| Field | What a client can do |
+| --- | --- |
+| `agents` | Run these agents, for example with `client.agents.<name>.start(input)`. |
+| `settings` | Change these [thread settings](./thread-settings) with `client.configure(settings)`. |
+| `config` | Set these plugin config keys with `client.setConfig({ key, value })`. |
+| `commands` | Run these commands with `client.command(name)`, or with `/name` in a [session view](./custom-ui) on a client. |
+
+- Any other input of these kinds gets `{ status: 'rejected', reason: 'not_exposed' }`.
+- `GET describe` and `client.describe()` list only the exposed commands and config keys. A UI built from them shows only what a client can use.
+- Server code that calls the session is not limited. `session.setConfig()` and `session.command()` work for every key and command, and `session.describe()` lists all of them.
+- `defineHarness` checks the names in `agents`. Plugins add their config keys and commands when a session opens, so it does not check those names.
+
+## Talk to it from a web app
+
+`createHarnessClient` wraps those endpoints. Import the harness with `import type`, so no server code reaches the browser.
+
+```ts group=harness-connect-client
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import type { assistant } from './harness'
+
+const client = createHarnessClient<typeof assistant>({
+  url: '/api/harness',
+  threadId: 'user-1-thread',
+  headers: { authorization: 'Bearer my-token' },
+})
+
+await client.prompt('Summarize my open tickets.')
+
+for await (const entry of client.events()) {
+  if (entry.event.type === 'TEXT_MESSAGE_CONTENT') {
+    console.log(entry.event.delta)
+  }
+}
+```
+
+`events()` reconnects after a network error and continues from the last cursor. A second tab, a phone, or a reload all see the same session.
+
+To upload files and show the media that your agents make, read [Send and show media](./media).
+
+## Send a message to a running agent
+
+A background agent runs for minutes, and the user wants to correct it from the page, or ask for one more change after it ends. The browser sends the run a message with `client.sendToAgent`.
+
+1. On the server, list the agent in `expose.agents`. A client can start and message only those agents:
+
+```ts group=harness-connect-agents
+import { defineAgent } from '@tanstack/ai'
+import { createHarnessHandler, createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+const drafter = defineAgent({
+  name: 'drafter',
+  description: 'Drafts a blog post',
+  run: (ctx) => ctx.chat({ adapter: openaiText('gpt-6.1-sol'), stream: false }),
+})
+
+export const studio = defineHarness({
+  name: 'acme/studio',
+  adapter: openaiText('gpt-6.1-sol'),
+  agents: [drafter],
+  expose: { agents: ['drafter'] },
+})
+
+export const handler = createHarnessHandler({
+  host: createHarnessHost({ persistence: memoryPersistence() }),
+  harness: studio,
+  authorize: (request) =>
+    request.headers.get('authorization') === `Bearer ${process.env.HARNESS_TOKEN}`
+      ? { id: 'user-1' }
+      : null,
+  canAccess: (principal, threadId) => threadId.startsWith(`${principal.id}-`),
+})
+```
+
+2. In the browser, send the message to the id of the run:
+
+```ts group=harness-connect-agents-client
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import type { studio } from './harness'
+
+const client = createHarnessClient<typeof studio>({
+  url: '/api/harness',
+  threadId: 'user-1-thread',
+  headers: { authorization: 'Bearer my-token' },
+})
+
+export async function correct(operationId: string) {
+  const receipt = await client.sendToAgent({
+    operationId,
+    message: 'Cite papers, not blogs.',
+  })
+  if (receipt.status === 'rejected') {
+    console.warn(receipt.reason)
+  }
+}
+
+export function addTitle(operationId: string) {
+  return client.sendToAgent({
+    operationId,
+    message: 'Add a title.',
+    mode: 'followUp',
+  })
+}
+```
+
+The id of the run is the `operationId` in the receipt of `client.agents.drafter.start()`. A [session view](./custom-ui#3-act-on-the-session) also lists the running agents with their ids.
+
+- `mode: 'steer'` (the default): the message joins the next model call of the run.
+- `mode: 'followUp'`: the agent runs again after the run ends. `receipt.operationId` is the id of the new run.
+
+`sendToAgent` posts an `agentMessage` input to `POST control`. It runs as the user that `authorize` returned. The input looks like this:
+
+```json
+{ "op": "agentMessage", "operationId": "op-agent-m1x2-3", "message": "Add a title.", "mode": "followUp" }
+```
+
+The session rejects the message with a `reason` in these cases:
+
+- `not_running`: the session does not know the run. Another host can run it, or the id is wrong.
+- `not_exposed`: the agent of the run is not in `expose.agents`.
+
+For how steers and follow-ups run on the server, see [Message a running agent](./subagents#message-a-running-agent).
+
+## Use it from useChat
+
+Your app already uses `useChat`. You want the same chat screen on a harness, with approvals, tools that run in the browser, and the thread after a reload. Point `useChat` at the `run` path of the handler.
+
+1. Put the tools in a file that the server and the browser both import:
+
+```ts group=harness-connect-tools
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+export const deploy = toolDefinition({
+  name: 'deploy',
+  description: 'Deploy the app. A person must approve it.',
+  needsApproval: true,
+  inputSchema: z.object({ env: z.string() }),
+  outputSchema: z.object({ ok: z.boolean() }),
+})
+```
+
+2. On the server, give the harness the tool with its implementation:
+
+```ts group=harness-connect-tools-server
+import { defineHarness } from '@tanstack/ai-harness'
+import { openaiText } from '@tanstack/ai-openai'
+import { deploy } from './tools'
+
+export const deployer = defineHarness({
+  name: 'acme/deployer',
+  adapter: openaiText('gpt-6.1-sol'),
+  tools: [
+    deploy.server(async () => {
+      // Your deploy code runs here.
+      return { ok: true }
+    }),
+  ],
+})
+```
+
+Serve `deployer` with `createHarnessHandler`, as in [Serve the session over HTTP](#serve-the-session-over-http).
+
+3. In the browser, give `useChat` the same tool definitions:
+
+```tsx group=harness-connect-tools-client
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import { deploy } from './tools'
+
+export function Chat() {
+  const { messages, interrupts, sendMessage } = useChat({
+    threadId: 'user-1-thread',
+    connection: fetchServerSentEvents('/api/harness/run'),
+    tools: [deploy.client()] as const,
+    // The input's context: tools and plugins read it.
+    forwardedProps: { page: '/releases' },
+  })
+
+  return (
+    <>
+      <p>{messages.length} messages</p>
+      {interrupts.map((interrupt) =>
+        interrupt.kind === 'tool-approval' ? (
+          <button
+            key={interrupt.id}
+            onClick={() => interrupt.resolveInterrupt(true)}
+          >
+            Approve {interrupt.toolName}
+          </button>
+        ) : null,
+      )}
+      <button onClick={() => sendMessage('Deploy to staging.')}>Deploy</button>
+    </>
+  )
+}
+```
+
+The approval reaches the harness, and the tool runs on the server. What else `POST run` does for `useChat`:
+
+- Each turn runs as the `runId` of its request. A retry with the same `runId` runs once. The same `runId` with another message gets `409`.
+- A tool with only a `.client()` implementation runs in the browser, and the same turn gets its result.
+- A question from `ctx.session.ask` arrives on the stream of the turn that waits for it.
+- The `forwardedProps` of the request are the input's [context](./inputs#send-context-with-a-message).
+- With `persistence: true`, `useChat` loads the thread from `GET run?threadId=`.
+- If a turn still runs after a reload, `useChat` joins it with `GET run?runId=`. The turn shows from its first event, and its answer continues to stream.
+- On a durable host (`stores.log` and `stores.runs`), each event of `POST run` has its log cursor as its id. If the connection drops, `useChat` sends the request again with `Last-Event-ID`. Any server continues the stream from there, and the turn does not run again.
+
+To keep the thread after a reload, set `persistence: true` in `useChat`:
+
+```tsx group=harness-connect-tools-client
+export function ReloadableChat() {
+  const { messages } = useChat({
+    threadId: 'user-1-thread',
+    connection: fetchServerSentEvents('/api/harness/run'),
+    tools: [deploy.client()] as const,
+    persistence: true,
+  })
+  return <p>{messages.length} messages</p>
+}
+```
+
+The join has these rules:
+
+- `canAccess` decides who can join, the same as for every other path.
+- On a durable host, any server can answer the join. It reads the turn from the shared log.
+- Without a log store, the turn must run on the host that answers the request. On another host, the join gets `404`.
+- A turn that ended gives the events that the session still keeps, and then the stream ends.
+
+## Use a WebSocket
+
+For one connection that carries events and inputs, authorize the upgrade, then hand the socket to `handleHarnessSocket`:
+
+```ts group=harness-connect
+import { handleHarnessSocket } from '@tanstack/ai-harness'
+import type { WebSocketLike } from '@tanstack/ai'
+
+export function onUpgrade(socket: WebSocketLike) {
+  handleHarnessSocket({
+    host,
+    harness: assistant,
+    socket,
+    principal: { id: 'user-1' },
+    canAccess: (principal, threadId) => threadId.startsWith(`${principal.id}-`),
+  })
+}
+```
+
+The client sends `{ type: 'harness.subscribe', threadId }` first. After that, each `harness.input` frame gets a `harness.receipt`, and every event arrives as a `harness.event` frame with its cursor.
+
+## Use it as the model of another chat
+
+`harnessText` turns a harness into a text adapter. The outer chat sends a message, and the harness runs a full turn with its own tools, plugins, and agents:
+
+```ts group=harness-connect
+import { chat } from '@tanstack/ai'
+import { harnessText } from '@tanstack/ai-harness'
+
+const stream = chat({
+  adapter: harnessText(assistant, { host }),
+  messages: [{ role: 'user', content: 'Fix the failing test.' }],
+  threadId: 'outer-thread',
+})
+```
+
+Each outer thread gets its own inner session, so the harness keeps its own history. The inner session gets every content part of the last user message, so images and files go through too.
+
+If a plugin picks the model of the harness, the harness has no adapter to read its input kinds from. Pass them with `harnessText(assistant, { host, inputModalities: ['text', 'image'] })`.
+
+## What you have now
+
+- One handler that serves standard AG-UI and the session stream.
+- Clients that can change only what you expose.
+- A `useChat` screen on the harness, with approvals, tools that run in the browser, and a reload that joins the running turn.
+- A typed web client that reconnects and resumes from a cursor.
+- Messages from the browser to a running agent.
+- A WebSocket, and a harness you can call from `chat()`.
+
+Next: send more than a prompt with [inputs](./inputs).
diff --git a/docs/harness/custom-ui.md b/docs/harness/custom-ui.md
new file mode 100644
index 0000000000..1052b1c6e5
--- /dev/null
+++ b/docs/harness/custom-ui.md
@@ -0,0 +1,608 @@
+---
+title: Build your own UI
+id: harness-custom-ui
+order: 13
+description: "Show a harness session in your own terminal screen or web app. One live store holds the messages, tool calls, approvals, and plugin state, and works with any UI library."
+keywords:
+  - tanstack ai
+  - harness
+  - session view
+  - tanstack store
+  - ink
+  - custom ui
+---
+
+You want your own screen for your harness: your own layout in a terminal, or a page in your web app. `session.events()` gives you raw AG-UI events. To show them, you must join text deltas, follow each tool call, and keep a list of open approvals. That is a reducer, and you must keep it correct.
+
+`createSessionView` does that work. It keeps one live state in a TanStack Store, and it gives you actions and typed events. You show the state with any UI library.
+
+At the end of this page you have a terminal screen in about 20 lines, and the same view in a web app.
+
+## Install
+
+Install the harness and the TanStack Store adapter for your UI library. With no UI library, the harness is enough.
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai-harness @tanstack/react-store
+vue: @tanstack/ai-harness @tanstack/vue-store
+solid: @tanstack/ai-harness @tanstack/solid-store
+svelte: @tanstack/ai-harness @tanstack/svelte-store
+preact: @tanstack/ai-harness @tanstack/preact-store
+angular: @tanstack/ai-harness @tanstack/angular-store
+vanilla: @tanstack/ai-harness
+octane: @tanstack/ai-harness
+
+<!-- ::end:tabs -->
+
+The terminal screen on this page uses Ink, which needs Node 22 or later. Install Ink and React too:
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: ink react
+
+<!-- ::end:tabs -->
+
+## 1. Make a view
+
+Open a session, then give it to `createSessionView`:
+
+```ts group=harness-custom-ui
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { createSessionView } from '@tanstack/ai-harness/view'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-6.1-sol'),
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+const session = await host.open(assistant, { threadId: 'thread-1' })
+
+const view = createSessionView(session)
+await view.ready
+```
+
+`view.ready` resolves when the view has the saved messages, the status, and the commands and settings of the session. If you open a thread again, its history is in the view immediately. And if a turn is still running when you open the view, you see that turn from its start, not only from the moment you opened it.
+
+## 2. Show the state
+
+`view.store` is a TanStack Store. `useSelector` reads one part of the state, and your component updates only when that part changes. This Ink screen shows the messages and the status:
+
+```tsx ignore
+import { Box, Text, render } from 'ink'
+import { useSelector } from '@tanstack/react-store'
+import type { SessionView } from '@tanstack/ai-harness/view'
+
+function Screen({ view }: { view: SessionView }) {
+  const messages = useSelector(view.store, (state) => state.messages)
+  const status = useSelector(view.store, (state) => state.status)
+  return (
+    <Box flexDirection="column">
+      {messages.map((message) =>
+        message.role === 'assistant' ? (
+          <Text key={message.id}>
+            {message.parts.map((part) => (part.type === 'text' ? part.text : '')).join('')}
+          </Text>
+        ) : (
+          <Text key={message.id} color="gray">
+            {message.role === 'user' ? `> ${message.text}` : message.text}
+          </Text>
+        ),
+      )}
+      <Text color="gray">{status}</Text>
+    </Box>
+  )
+}
+
+render(<Screen view={view} />)
+await view.send('Summarize the README.')
+```
+
+Put the code of steps 1 and 2 in one `.tsx` file, then run it. The screen shows your prompt, then the answer while it streams, then the status `idle`. Press Ctrl+C to quit.
+
+Each TanStack Store adapter reads the store the same way. Vue, Solid, Svelte, and Preact have `useSelector`. Angular has `injectSelector`. With no UI library, subscribe to the store:
+
+```ts group=harness-custom-ui
+const subscription = view.store.subscribe((state) => {
+  console.log(`${state.status}: ${state.messages.length} messages`)
+})
+```
+
+Call `subscription.unsubscribe()` to stop.
+
+### What the state holds
+
+The conversation:
+
+- `messages`: the lines to show. Each message has a `role`: `user`, `assistant`, or `notice`.
+- `status`: `idle`, `running`, or `requires_action`.
+- `connection`: `open`, `reconnecting`, or `closed`.
+
+What waits for the user:
+
+- `approvals`: tool calls that wait for a yes or a no.
+- `clientTools`: tool calls that run in your UI and wait for their output. See [Run a tool in the browser](#run-a-tool-in-the-browser).
+- `interrupts`: everything else a turn can wait for, for example a value that a tool asks for. See [Answer other interrupts](#answer-other-interrupts).
+- `questions`: questions from a command, a plugin, or an MCP server. See [Show a question](#show-a-question).
+- `signIns`: connectors that need a sign-in, with a `url` and a `userCode` when the connector gives them.
+
+The session:
+
+- `threadId`: the id of the conversation.
+- `agents`: the background agents that run now. Each one has an `id`, a `name`, `send`, and `cancel`.
+- `queuedTurns` and `waitingInputs`: how many messages wait for their turn, and which ones, in the order they run.
+- `plugins`: the saved state of each plugin, by plugin name.
+
+Settings and usage, for a settings panel or a status bar:
+
+- `commands`, `config`, and `tools`: what the session has, for a help screen.
+- `models`: the model names from `defineHarness({ models })`, for a model menu.
+- `settings`: the stored settings of the thread, for example the model it uses now.
+- `usage`: the token usage of the thread. It updates after each model call.
+
+An assistant message has `parts`. Each part is one of these:
+
+- `text` or `reasoning`: the text, which grows while it streams.
+- `tool-call`: a tool call with its `name`, `args`, and `status` (`running`, `done`, `failed`, or `needs-approval`).
+- `agent`: a child agent, with its own `parts`, its `status`, and its `result` when it gives one. See [Show subagents](#show-subagents).
+- `media`: a file that an agent made. See [Show media](#show-media).
+
+A notice has a `kind`:
+
+- `info`: the session continues a turn that a crash stopped, or a [reset](./fork-and-reset#reset-with-a-handoff-note) started a fresh context.
+- `error`: a turn or an action failed.
+- `rejected`: the session did not accept a message.
+- `command`: the text result of a command.
+- `ui`: a line that you added with `view.notice(text)`.
+
+## 3. Act on the session
+
+Send work:
+
+- `view.send(text)`: sends a prompt. While a turn runs, the text steers that turn. Text that starts with `/` runs a command, for example `/goal all tests pass`.
+- `view.followUp(text)`: the message waits, and runs as its own turn after the current work.
+- `view.continue()`: starts a turn from the saved messages, with no new message.
+- `view.command(name, input)`: runs a command, for example from a button.
+- `view.upload(bytes, { name, mimeType })`: stores a file. Send the record you get back with `view.send(text, [record])`. See [Show media](#show-media).
+
+Change the session:
+
+- `view.setConfig({ key, value })`: changes a config value, for example `view.setConfig({ key: 'mode', value: 'plan' })`.
+- `view.configure(settings)`: changes the stored settings of the thread, for example `view.configure({ model: 'strong' })`.
+- `view.reset(note)`: the model starts fresh from the next turn, with your `note` first. See [Reset with a handoff note](./fork-and-reset#reset-with-a-handoff-note).
+- `view.revert(messageId)` and `view.unrevert()`: go back to a message, and undo that.
+
+Stop work:
+
+- `view.cancel()`: cancels the running turn. `view.cancel(operationId)` cancels one operation, for example a background agent.
+- `view.cancelInput(inputId)`: drops a message from `waitingInputs` before it runs. `view.setDelivery({ inputId, delivery: 'steer' })` moves it into the running turn instead.
+- `view.dispose()`: stops the view when your screen closes. After that, each action throws an error.
+
+On a view with a [`HarnessClient`](#a-ui-in-the-browser), two actions need `expose` in the harness:
+
+- `view.command`, and a `/command` in `view.send`, run only the commands in `expose.commands`.
+- `view.setConfig` sets only the keys in `expose.config`.
+
+For any other command or key, the view adds a `rejected` notice with the text `Not accepted: not_exposed`. It also calls your `'error'` handler with that text. On a client, `commands` and `config` in the state list only the exposed items.
+
+See [Choose what clients can change](./connect#choose-what-clients-can-change).
+
+Answer what waits:
+
+- `approval.approve()` and `approval.reject()`: answer one approval. `view.approve(id)` and `view.reject(id)` do the same by id.
+- `view.approveAll()` and `view.rejectAll()`: answer all open approvals.
+- `call.resolve(output)` and `call.fail(message)`: answer one client tool call.
+- `request.resolve(value)` and `request.cancel()`: answer one item of `interrupts`.
+- `question.answer(value)`: answers a question.
+
+Want the tool to run with different arguments than the model picked? Pass them to `approve`:
+
+```ts group=harness-custom-ui
+const [waiting] = view.store.get().approvals
+waiting?.approve({ editedArgs: { path: 'notes/draft.md' } })
+```
+
+`reject(payload)` sends data with a no, when the tool's approval schema takes some.
+
+If a turn waits for more than one approval, client tool, or interrupt, the turn continues after you answer all of them.
+
+Message a background agent:
+
+- `agent.send(text, { mode })`: sends a message to one item of `state.agents`. `mode` is `'steer'` (the default) or `'followUp'`. See [Message a running agent](./subagents#message-a-running-agent).
+
+```ts group=harness-custom-ui
+const [agent] = view.store.get().agents
+if (agent) {
+  await agent.send('Add a title.', { mode: 'followUp' })
+}
+```
+
+`agent.cancel()` stops the run, and the runs it started.
+
+A session and a `HarnessClient` can do all of this. If you give `createSessionView` your own `SessionViewSource`, some members are optional. Without `sendToAgent`, `agent.send` rejects with an error. Without `followUp`, `reset`, or another optional member, its action adds an `error` notice instead.
+
+## 4. Listen for events
+
+Some items need attention when they arrive. `view.on` calls your handler for each one. When a tool call waits for approval, this handler rings the terminal bell and adds a line to the screen:
+
+```ts group=harness-custom-ui
+view.on('approval', (approval) => {
+  process.stdout.write('\u0007')
+  view.notice(`${approval.tool} waits for your answer.`)
+})
+```
+
+Items that wait for the user:
+
+- `'approval'`: an approval. Call `approve()` or `reject()` on it.
+- `'clientTool'`: a client tool call. Call `resolve(output)` or `fail(message)` on it.
+- `'interrupt'`: an item of `interrupts`. Call `resolve(value)` or `cancel()` on it.
+- `'question'`: a question with a `message`, a `schema`, a `url` when the user must open a page, and `answer(value)`.
+- `'signIn'`: a connector that needs a sign-in, with `connector`, `url`, and `userCode`.
+
+Progress:
+
+- `'toolCall'`: `{ id, name }`, when a tool call starts.
+- `'agent'`: `{ id, name, status }`, when a child agent starts, finishes, or fails.
+- `'error'`: the error text. The view also adds it to `messages` as a notice.
+- `'turnEnd'`: `{ operationId }`, when a chat turn ends. A turn that stops for an approval has not ended, so it does not fire then.
+
+The view calls your handler after the item is in the state, so the handler can read `view.store.get()` and find the item. `view.on` returns a function that removes the handler.
+
+## Show a question
+
+A command or a plugin can ask the user a question. Each item of `state.questions` has:
+
+- `id` and `message`.
+- `schema`: the JSON Schema of the answer, when the question has one. Without a schema, the answer is text.
+- `secret`: the answer is a key or a password. Hide what the user types.
+- `url`: a page that the user must open before they answer, for example a payment page.
+- `answer(value)`: sends the answer.
+
+When a question has a `url`, show the link. The user opens it, then answers. The session does not open the page. This handler adds the link to the screen:
+
+```ts group=harness-custom-ui
+view.on('question', (question) => {
+  if (question.url) view.notice(`Open ${question.url}, then answer.`)
+})
+```
+
+### Show a field only when it applies
+
+A schema can make a field apply only when another field has a value. JSON Schema writes this with `if` and `then`. In this schema, `address` applies only when `delivery` is `mail`:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "delivery": { "type": "string", "enum": ["pickup", "mail"] },
+    "address": { "type": "string" }
+  },
+  "required": ["delivery"],
+  "if": { "properties": { "delivery": { "const": "mail" } } },
+  "then": { "required": ["address"] }
+}
+```
+
+The view gives you the schema as is. Your UI reads the condition. This function returns the fields that `then` adds for the answer so far:
+
+```ts group=harness-custom-ui
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function fieldsThatApply(schema: unknown, answer: Record<string, unknown>) {
+  if (!isRecord(schema) || !isRecord(schema.if) || !isRecord(schema.then)) {
+    return []
+  }
+  const rules = isRecord(schema.if.properties)
+    ? Object.entries(schema.if.properties)
+    : []
+  const matches = rules.every(
+    ([field, rule]) => isRecord(rule) && answer[field] === rule.const,
+  )
+  const required = schema.then.required
+  return matches && Array.isArray(required) ? required : []
+}
+```
+
+Call it each time the user changes a field. Show a field from the result, and hide it again when the result no longer has it:
+
+```ts group=harness-custom-ui
+const [question] = view.store.get().questions
+const extra = fieldsThatApply(question?.schema, { delivery: 'mail' })
+// With the schema above, `extra` is ['address'].
+```
+
+## Answer other interrupts
+
+Some turns wait for something that is not a yes or a no. A tool can stop the turn to ask for a value, or your own code can stop it for a form. The view puts these in `state.interrupts`. Each item has:
+
+- `id`, `reason`, and `message`: what the turn waits for. `reason` is the name the interrupt gave itself, for example `pick_region`.
+- `payload`: the data the interrupt sent for your UI, for example the fields of a form.
+- `responseSchema`: the JSON Schema of the answer, when it has one. [Show a field only when it applies](#show-a-field-only-when-it-applies) works for it too.
+- `resolve(value)`: sends the answer.
+- `cancel()`: answers with no value, and the turn continues without one.
+
+This handler shows each one, and answers the region picker right away:
+
+```ts group=harness-custom-ui
+view.on('interrupt', (request) => {
+  view.notice(request.message ?? `The turn waits for ${request.reason}.`)
+  if (request.reason === 'pick_region') request.resolve({ region: 'eu-west-1' })
+})
+```
+
+## Show media
+
+A user sends a screenshot, and an agent draws an image. The view gives you each file as a media part, with a URL that works in `<img>`, `<audio>`, and `<video>`.
+
+The media parts are in these places:
+
+- `media` of a user message: the files that the user sent.
+- `parts` of an `agent` part: the files that this child agent made.
+- `parts` of an assistant message, at the end: the files of the turn, after the view loads the history again (for example after a restart).
+
+This component shows the parts of a message, with the parts of each child agent:
+
+```tsx
+import type { MediaPart, ViewPart } from '@tanstack/ai-harness/view'
+
+function Media({ part }: { part: MediaPart }) {
+  if (part.url === undefined) return <span>{part.name}</span>
+  if (part.kind === 'image') return <img src={part.url} alt={part.name} />
+  if (part.kind === 'audio') return <audio controls src={part.url} />
+  if (part.kind === 'video') return <video controls src={part.url} />
+  return (
+    <a href={part.url} download={part.name}>
+      {part.name}
+    </a>
+  )
+}
+
+export function Parts({ parts }: { parts: Array<ViewPart> }) {
+  return (
+    <>
+      {parts.map((part, index) => {
+        if (part.type === 'text') return <p key={index}>{part.text}</p>
+        if (part.type === 'media') return <Media key={part.id} part={part} />
+        if (part.type === 'agent') return <Parts key={part.id} parts={part.parts} />
+        return null
+      })}
+    </>
+  )
+}
+```
+
+A media part has:
+
+- `id`, `kind`, `mimeType`, `name`, and `size` (in bytes).
+- `url`: a URL for the file, when the source can give one. The view gets a new URL before the old one expires.
+- `load()`: the bytes of the file, as a `Uint8Array`.
+
+Where `url` comes from:
+
+- With `createHarnessClient`, `url` is a signed URL from the handler. See [Send and show media](./media).
+- With a local session, `url` is a data URL for a file up to 1 MB. A bigger file has no `url`, so use `load()`.
+
+To send files with a message, give their records to `view.send`. This code sends a screenshot from the disk:
+
+```ts group=harness-custom-ui
+import { readFile } from 'node:fs/promises'
+
+const screenshot = await session.putMedia(await readFile('./bug.png'), {
+  mimeType: 'image/png',
+  name: 'bug.png',
+})
+await view.send('What is wrong in this screenshot?', [screenshot])
+```
+
+In a browser, get the record from `client.upload(file, { name: file.name, mimeType: file.type })`. The user message then shows the file in `media`.
+
+## Show subagents
+
+A child agent is an `agent` part in the assistant message of the turn that started it. The component in [Show media](#show-media) already draws one, with its own parts inside. On top of `parts`, each `agent` part has:
+
+- `status`: `running`, `done`, or `failed`, and `error` when it failed.
+- `result`: the typed result of the agent, when it gives one.
+
+After a reload, each child shows up again with what it wrote, not only with its final result. The view reads the saved messages of each child (see [Show what a child wrote after a reload](./subagents#show-what-a-child-wrote-after-a-reload)) and fills its part. A background child that still runs keeps getting its new text in the same part.
+
+To show a line when a child ends, listen for `'agent'`:
+
+```ts group=harness-custom-ui
+view.on('agent', (child) => {
+  if (child.status !== 'running') view.notice(`${child.name} is ${child.status}.`)
+})
+```
+
+## Plugin state and plugin events
+
+Plugins show their work through state and events. `state.plugins` holds the saved state of each plugin, by plugin name.
+
+`view.on` takes any plugin event from `createPluginEvent`, and the handler gets its typed value:
+
+```ts group=harness-custom-ui
+import { createPluginEvent } from '@tanstack/ai-harness'
+
+const Deployed = createPluginEvent<{ env: string }>('acme/deploy:done')
+
+view.on(Deployed, (done) => view.notice(`Deployed to ${done.env}`))
+```
+
+`state.plugins` is plugin data, so check its shape before you use it.
+
+## A UI in the browser
+
+Your harness runs on a server, and your UI is a web page. Give `createSessionView` a `HarnessClient` in place of a session. The state, the actions, and the events stay the same.
+
+### On the server
+
+Serve the session with `createHarnessHandler`, and mount the handler on `/api/harness`:
+
+```ts group=harness-custom-ui-server
+import { createHarnessHandler, createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-6.1-sol'),
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+
+export const handler = createHarnessHandler({
+  host,
+  harness: assistant,
+  authorize: (request) =>
+    request.headers.get('authorization') === `Bearer ${process.env.HARNESS_TOKEN}`
+      ? { id: 'user-1' }
+      : null,
+  canAccess: (principal, threadId) => threadId.startsWith(principal.id),
+})
+```
+
+The handler also serves `GET transcript` and `GET describe`. The view reads them when it starts. For the other routes, see [Connect clients](./connect).
+
+### In the browser
+
+Make the view one time, in code that runs in the browser. Then read it in your components:
+
+```tsx ignore
+import { useState } from 'react'
+import { useSelector } from '@tanstack/react-store'
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import { createSessionView } from '@tanstack/ai-harness/view'
+
+const view = createSessionView(
+  createHarnessClient({
+    url: '/api/harness',
+    threadId: 'user-1-thread',
+    headers: { authorization: 'Bearer my-token' },
+  }),
+)
+
+export function Chat() {
+  const messages = useSelector(view.store, (state) => state.messages)
+  const approvals = useSelector(view.store, (state) => state.approvals)
+  const connection = useSelector(view.store, (state) => state.connection)
+  const [draft, setDraft] = useState('')
+
+  return (
+    <main>
+      <p role="status">{connection === 'reconnecting' ? 'Reconnecting...' : ''}</p>
+      {messages.map((message) => (
+        <p key={message.id}>
+          {message.role === 'assistant'
+            ? message.parts.map((part) => (part.type === 'text' ? part.text : '')).join('')
+            : message.text}
+        </p>
+      ))}
+      {approvals.map((approval) => (
+        <p key={approval.id}>
+          Run {approval.tool}?{' '}
+          <button type="button" onClick={approval.approve}>
+            Yes
+          </button>
+          <button type="button" onClick={approval.reject}>
+            No
+          </button>
+        </p>
+      ))}
+      <form
+        onSubmit={(event) => {
+          event.preventDefault()
+          void view.send(draft)
+          setDraft('')
+        }}
+      >
+        <input aria-label="Message" value={draft} onChange={(event) => setDraft(event.target.value)} />
+        <button type="submit">Send</button>
+      </form>
+    </main>
+  )
+}
+```
+
+`connection` tells the user about the network:
+
+- `open`: events arrive.
+- `reconnecting`: the connection dropped. The client connects again and continues after the last event.
+- `closed`: the view stopped reading events, for example after `view.dispose()`.
+
+## Run a tool in the browser
+
+Some tools must run where the user is, for example a tool that opens a screen of your app. The server cannot run them. Give the harness the tool with no `.server()` implementation. The turn then waits, and the view lists the call in `clientTools`. Your page runs the tool and sends the output.
+
+1. Put the tool in a file that the server and the browser both import:
+
+```ts group=harness-custom-ui-tools
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+export const openScreenInput = z.object({ route: z.string() })
+
+export const openScreen = toolDefinition({
+  name: 'openScreen',
+  description: 'Open a screen of the app for the user.',
+  inputSchema: openScreenInput,
+  outputSchema: z.object({ opened: z.boolean() }),
+})
+```
+
+2. On the server, give the tool to the harness:
+
+```ts group=harness-custom-ui-tools-server
+import { defineHarness } from '@tanstack/ai-harness'
+import { openaiText } from '@tanstack/ai-openai'
+import { openScreen } from './tools'
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-6.1-sol'),
+  tools: [openScreen],
+})
+```
+
+3. In the browser, run the tool when the view gets the call:
+
+```ts group=harness-custom-ui-tools-client
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import { createSessionView } from '@tanstack/ai-harness/view'
+import { openScreenInput } from './tools'
+
+const view = createSessionView(
+  createHarnessClient({ url: '/api/harness', threadId: 'user-1-thread' }),
+)
+
+view.on('clientTool', (call) => {
+  if (call.tool !== 'openScreen') return
+  const input = openScreenInput.safeParse(call.args)
+  if (!input.success) {
+    call.fail('The route is not a string.')
+    return
+  }
+  history.pushState({}, '', input.data.route)
+  call.resolve({ opened: true })
+})
+```
+
+A client tool call has:
+
+- `tool` and `args`: the tool name and the input that the model gave.
+- `resolve(output)`: sends the output. The model gets it as the tool result.
+- `fail(message)`: sends a failure. The model sees that the tool failed with `message`.
+
+A turn can wait for approvals and client tools at the same time. When each item has an answer, the view sends all the answers together. Then the turn continues. To show the calls in a component, read `state.clientTools` with `useSelector`, the same as `approvals`.
+
+## What you have now
+
+- A terminal screen in about 20 lines, with no event loop and no reducer.
+- The same view in a web app, on a harness that runs on a server.
+- Tools that run in the browser, with their output sent back from the view.
+- Actions, typed events, and plugin state that work with any UI library.
+- Images, audio, and video from the session, with URLs that the view keeps valid.
diff --git a/docs/harness/durable-sessions.md b/docs/harness/durable-sessions.md
index 1434480a07..c7d29257c8 100644
--- a/docs/harness/durable-sessions.md
+++ b/docs/harness/durable-sessions.md
@@ -65,7 +65,7 @@ When a host opens the thread and finds a turn whose lease expired, it checks the
 4. The time limit passed: the input ends `failed`, with the error code `timeout`.
 5. Else the turn runs again as the next attempt, and clients get a `harness.operation.resumed` event.
 
-An input that was stored but never ran, runs now. `session.settled(inputId)` resolves to how an input ended.
+An input that was stored but never ran, runs now. `session.settled(inputId)` resolves to how an input ended. See [Send inputs safely](./inputs).
 
 A background agent that you started with `resume: true` runs again on the next host. See [Keep a background agent going after a crash](./subagents#keep-a-background-agent-going-after-a-crash). For any other background agent, when its lease expired, the next host:
 
diff --git a/docs/harness/fork-and-reset.md b/docs/harness/fork-and-reset.md
index 2aca920ac1..6d3684b14b 100644
--- a/docs/harness/fork-and-reset.md
+++ b/docs/harness/fork-and-reset.md
@@ -93,7 +93,7 @@ export async function startFresh(threadId: string) {
 What the reset does:
 
 - The note reaches the model as a user message, as you wrote it. Write it as a summary or a handoff. Without a note, the model sees only what comes after the reset.
-- `transcript()` keeps every message. The reset adds a marker message with `metadata.harness.reset`, so a UI can draw a line there. The session also sends a `harness.reset` event.
+- `transcript()` keeps every message. The reset adds a marker message with `metadata.harness.reset`, so a UI can draw a line there. The session also sends a `harness.reset` event. The [session view](./custom-ui) shows it as an `info` notice.
 - If a turn runs, the reset waits. It applies when that turn ends, before the next queued turn.
 - While the thread waits for interrupts, the reset is refused with `pending_interrupts`. Answer the interrupts first.
 - It is an input, so it runs once per `inputId`. On a durable host, the reset stays after a restart, and [compaction](./compaction) after a reset sees only the new context.
diff --git a/docs/harness/inputs.md b/docs/harness/inputs.md
new file mode 100644
index 0000000000..29bbebec59
--- /dev/null
+++ b/docs/harness/inputs.md
@@ -0,0 +1,327 @@
+---
+title: Send inputs safely
+id: harness-inputs
+order: 4
+description: "Give each prompt your own id, so a network retry does not run it twice. Ask the session how an input ended, and cancel or move a message that waits."
+keywords:
+  - tanstack ai
+  - harness
+  - inputId
+  - idempotency
+  - settled
+  - steer
+  - cancelInput
+  - setDelivery
+  - background
+---
+
+A network retry can send the same prompt twice, and a client that reconnects does not know how its last prompt ended. Give each input your own id. A retry with the same id runs nothing again, and the session tells you how the input ended.
+
+## Send a prompt with your own id
+
+On the server, pass `inputId` to `prompt`. `await turn.receipt` resolves when the session stored the input.
+
+```ts group=harness-inputs
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-6.1-sol'),
+})
+const host = createHarnessHost({
+  persistence: {
+    stores: { log: memoryLogStore(), runs: memoryPersistence().stores.runs },
+  },
+})
+const session = await host.open(assistant, { threadId: 'user-1-thread' })
+
+const turn = session.prompt('Summarize the report.', { inputId: 'req-42' })
+const receipt = await turn.receipt
+console.log(receipt.status) // 'accepted' or 'queued'
+```
+
+- The same id and the same message: you get the first input's operation, and the model is not called again.
+- The same id and another message: the receipt has `status: 'rejected'` and `reason: 'conflict'`, and `await turn` rejects with `InputRejectedError`.
+- `steer`, `followUp`, and `resolve` take `{ inputId }` too.
+- [`configure`](./thread-settings) and [`reset`](./fork-and-reset#reset-with-a-handoff-note) are inputs too. They take `{ inputId }` and run once per id.
+
+## Retry from the client
+
+The client sends the same `inputId` again after a network error. The second call gets the first receipt.
+
+```ts group=harness-inputs-client
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import type { AnyHarness } from '@tanstack/ai-harness'
+
+const client = createHarnessClient<AnyHarness>({
+  url: '/api/harness',
+  threadId: 'user-1-thread',
+})
+
+const send = () => client.prompt('Summarize the report.', { inputId: 'req-42' })
+const receipt = await send().catch(send)
+console.log(receipt.operationId)
+```
+
+Make the id once per user action (a button press), and keep it for every retry of that action.
+
+## Wait for the outcome
+
+On the server, `session.settled(inputId)` waits until the input ends. On a durable host it reads the log, so it also works after a restart and on another host that opens the thread.
+
+```ts group=harness-inputs
+const settlement = await session.settled('req-42')
+if (settlement.outcome === 'failed') {
+  console.log(settlement.error?.code) // 'attempts_exhausted', 'timeout', or undefined
+}
+```
+
+- `completed`: the turn has its answer.
+- `failed`: the turn failed. `error.code` is set for a limit.
+- `aborted`: someone cancelled the turn.
+- `interrupted`: the turn waits for human input. The `resolve` that answers it is a new input.
+
+If the turn fails after an approved tool ran (for example, the next model call fails), the interrupt is used up, and the tool does not run again. Its result stays in the transcript. To go on, send a new message. If a resume stopped before its tool ran, the interrupt stays open, and you can resolve it again.
+
+A client gets the same answer as a `harness.input.settled` event:
+
+```ts group=harness-inputs-client
+for await (const entry of client.events()) {
+  const { event } = entry
+  if (event.type === 'CUSTOM' && event.name === 'harness.input.settled') {
+    console.log(event.value)
+  }
+}
+```
+
+## Continue without a new message
+
+Sometimes the transcript already holds what the model must answer, for example a tool result that your own system stored. Start a turn with `continue`, and the model answers the stored transcript. No new user message goes in:
+
+```ts group=harness-inputs
+const continued = session.continue({ inputId: 'req-43' })
+await continued
+```
+
+From the client:
+
+```ts group=harness-inputs-client
+const continuedReceipt = await client.continue({ inputId: 'req-43' })
+```
+
+- `inputId` works as for `prompt`: a retry with the same id runs once.
+- `continue` takes `overrides`, `principal`, and `context` too, as `prompt` does.
+- When the turn starts, the last message of the transcript must be a user message or a tool result. Else the input is rejected with the reason `nothing_to_continue`, and `await continued` rejects with `InputRejectedError`.
+- A `continue` that a host left after a crash runs on the next host, as a prompt does.
+
+## Give the model a note for one turn
+
+A reminder such as "call `finish` or `give_up`" helps the model in one turn, but it does not belong in the transcript. Pass it as `ephemeral` to `prompt` or `continue`:
+
+```ts group=harness-inputs
+const reminded = session.continue({
+  inputId: 'req-44',
+  ephemeral: [{ role: 'user', content: 'Call finish or give_up now.' }],
+})
+await reminded
+```
+
+From the client:
+
+```ts group=harness-inputs-client
+const remindedReceipt = await client.prompt('Summarize the report.', {
+  inputId: 'req-45',
+  ephemeral: [{ role: 'user', content: 'Answer in three bullets.' }],
+})
+```
+
+- Each model call of the turn gets the messages right after the turn's own message (or the last stored message, for `continue`), before the answers and tool results of the turn.
+- The transcript, the session log, and the message store never keep them.
+- A retry with the same `inputId` gets the first input, also when its `ephemeral` messages are different.
+- A turn that recovery runs again after a crash has no `ephemeral` messages, because the log does not keep them.
+- From the client, `ephemeral` takes user messages only. On the server, `session.prompt` and `session.continue` take any message.
+
+To add a note from a hook when the model stops, see [Remind the model without saving the reminder](./turn-control#remind-the-model-without-saving-the-reminder).
+
+## Send a message while a turn runs
+
+With `busy: 'steer'`, a prompt joins the running turn. It reaches the model at the next model call, in the order the messages arrived, and it ends with that turn.
+
+```ts group=harness-inputs
+const running = session.prompt('Plan the migration.', { inputId: 'req-43' })
+const joined = session.prompt('Keep it under five steps.', {
+  busy: 'steer',
+  inputId: 'req-44',
+})
+// One turn answers both, so both get its result.
+await Promise.all([running, joined])
+console.log((await session.settled('req-44')).operationId === running.id) // true
+```
+
+A message that arrives while the model writes its final answer still gets an answer in the same turn.
+
+Waiting `steer` inputs join before each model call, in the order they arrived. They join as a prefix: the join stops at the first input that has an abort request, or that `turn.canJoin` refuses. The inputs after it wait.
+
+- The `operationId` in the receipt of a `busy: 'steer'` prompt or a `session.steer` input is the running turn. A cancel with that id cancels the turn.
+- A `busy: 'steer'` prompt also has its own operation, `joined`. To stop it before it joins, call `joined.cancel()` or `session.cancel(joined.id)`. It does not join, and it settles `aborted` when the running turn ends.
+- The session rejects a cancel that comes after the join started, with `reason: 'not_running'`.
+- A refused or late input runs as its own turn after the running one.
+
+To choose which inputs join, or to add records when they join, see [Choose which messages join a turn](./turn-control#choose-which-messages-join-a-turn).
+
+## Cancel or move a waiting message
+
+A user sends two more messages while a turn runs. Before they run, the user wants to cancel one, and wants the other to reach the running turn now. `session.inputs()` lists the inputs that wait. `cancelInput` cancels one, and `setDelivery` moves one:
+
+```ts group=harness-inputs
+const migration = session.prompt('Plan the migration.', { inputId: 'req-45' })
+// The turn runs, so these two wait for their own turns.
+await session.followUp('Then write the tests.', { inputId: 'req-46' })
+await session.followUp('Use tabs, not spaces.', { inputId: 'req-47' })
+
+for (const input of session.inputs()) {
+  console.log(input.inputId, input.delivery, input.message)
+}
+
+await session.cancelInput('req-46')
+await session.setDelivery({ inputId: 'req-47', delivery: 'steer' })
+await migration
+```
+
+- `inputs()` lists the inputs in the order they run: first the steers for the running turn, then the queued turns.
+- `delivery: 'steer'`: the input joins the running turn at the next model call. `'queue'`: it runs as its own turn, after the turns before it.
+- A cancelled input never runs, also after a restart. It settles `aborted`.
+- On a durable host, the log keeps a new delivery, and a restart obeys it. Without a log, the delivery stays in memory.
+- If the input started, or joins the running turn now, the receipt has `status: 'rejected'` and `reason: 'not_waiting'`. To stop it, cancel its operation with `session.cancel(operationId)`.
+
+A client reads the waiting inputs from the snapshot, and sends the same two inputs:
+
+```ts group=harness-inputs-client
+const { waitingInputs = [] } = await client.snapshot()
+for (const input of waitingInputs) {
+  console.log(input.inputId, input.delivery)
+}
+
+await client.cancelInput('req-46')
+await client.setDelivery({ inputId: 'req-47', delivery: 'steer' })
+```
+
+Over `POST control`, they are `{ op: 'cancelInput', inputId }` and `{ op: 'setDelivery', inputId, delivery }`. In these two inputs, `inputId` is the id of the input that waits. A move sends a `harness.input.delivery` event with `inputId` and `delivery`, so every client can update its list.
+
+## Move a running tool call to the background
+
+A long command or a subagent blocks the turn, and the user wants to go on. `session.background()` moves the running tool call to the background:
+
+```ts group=harness-inputs
+const build = session.prompt('Run the full test suite.', { inputId: 'req-48' })
+// Later, while the `bash` call of that turn runs:
+const moved = await session.background()
+console.log(moved.status) // 'accepted', or 'rejected' with 'not_running'
+await build
+```
+
+- The tool call returns at once. The model gets a short note with the job id, and the turn goes on.
+- The job keeps running. When it ends, the model gets its result as a note, and an idle session starts a new turn.
+- Without an argument, it moves every running call that supports it. Pass a `toolCallId` to move one call.
+- `bash` and the single `subagent` tool support it. Other tools keep running as before.
+- With no running call that supports it, the receipt has `status: 'rejected'` and `reason: 'not_running'`.
+- On a durable host (one with `stores.log`), the log keeps each job until it ends. When a crash stops a job, the next host adds the note "Background job call-1 stopped when the host restarted."
+- Without `stores.log`, the job lives in memory only. A crash stops it, and no note comes.
+
+A client sends `{ op: 'background' }` over `POST control`. It runs no new code, so it needs no `expose` entry:
+
+```ts group=harness-inputs-client
+await fetch('/api/harness/control', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({
+    threadId: 'user-1-thread',
+    input: { op: 'background' },
+  }),
+})
+```
+
+Your own tool can support it too. Pass its work to `detach` from the tool context, and race the two promises:
+
+```ts group=harness-inputs
+const longReport = toolDefinition({
+  name: 'longReport',
+  description: 'Build the monthly report',
+  inputSchema: z.object({}),
+}).server((_input, toolContext) => {
+  const work = new Promise<string>((resolve) => {
+    setTimeout(() => resolve('The report is ready.'), 60_000)
+  })
+  const detach = toolContext?.detach
+  return detach ? Promise.race([work, detach(work)]) : work
+})
+```
+
+## Send context with a message
+
+Your tools often need to know what the user looks at: the open record, the page, or the locale. Send it as the `context` of the input. The session stores it with the input, so a turn that runs again after a restart gets the same value.
+
+On the server, a tool reads it from its tool context:
+
+```ts group=harness-inputs
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+const openRecord = toolDefinition({
+  name: 'openRecord',
+  description: 'Read the id of the record that the user has open',
+  inputSchema: z.object({}),
+}).server(async (_input, toolContext) => {
+  const context = toolContext?.context
+  const recordId =
+    typeof context === 'object' && context !== null && 'recordId' in context
+      ? String(context.recordId)
+      : 'none'
+  return { recordId }
+})
+
+const records = defineHarness({
+  name: 'acme/records',
+  adapter: openaiText('gpt-6.1-sol'),
+  tools: [openRecord],
+})
+const recordSession = await host.open(records, { threadId: 'user-1-records' })
+
+await recordSession.prompt('Summarize the record I have open.', {
+  context: { recordId: 'inv-42' },
+})
+```
+
+`prompt`, `steer`, and `followUp` take `context`. A client sends it in a `control` input:
+
+```ts group=harness-inputs-client
+await fetch('/api/harness/control', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({
+    threadId: 'user-1-thread',
+    input: {
+      op: 'prompt',
+      message: 'Summarize the record I have open.',
+      context: { recordId: 'inv-42' },
+    },
+  }),
+})
+```
+
+On `POST run`, the AG-UI `forwardedProps` of the request are the `context`, for example `useChat({ forwardedProps })`. See [Connect clients to a harness](./connect).
+
+- The `context` is part of the input for the `inputId` check. An input with the same id and another `context` gets `'conflict'`.
+- When `HarnessConfig.context` and the input `context` are both plain objects, tools get them merged, and the harness value wins for a key in both. In all other cases, tools get the harness value. If the harness has no value, tools get the input value.
+- Plugins and the router get it as `turn.context`. See [Pick the model of a turn](./plugins#pick-the-model-of-a-turn).
+- The `context` is client data, so do not trust it. Who sent the input is the principal from `authorize`. See [Share a thread](./shared-threads).
+
+## What you have now
+
+- Retries that never run a prompt twice.
+- The outcome of each input by its id, also after a restart.
+- Messages that join a running turn in order.
+- Waiting messages that a user can cancel, or move into the running turn, and running jobs that a user can move to the background.
+- Context from the client that tools read, also after a restart.
diff --git a/docs/harness/mcp-server.md b/docs/harness/mcp-server.md
new file mode 100644
index 0000000000..25c2e414a5
--- /dev/null
+++ b/docs/harness/mcp-server.md
@@ -0,0 +1,243 @@
+---
+title: Use a harness from any MCP client
+id: harness-mcp-server
+order: 9
+description: "Serve your harness as an MCP server. Chat with it, answer its approvals, and run its agents and commands from Claude Code, Claude Desktop, Cursor, or another agent."
+keywords:
+  - tanstack ai
+  - harness
+  - mcp
+  - mcp server
+  - claude code
+  - cursor
+---
+
+You built a harness, but you do your work in Claude Code, Cursor, or another agent. You want to give work to your harness from there. These clients speak MCP. `createHarnessMcpServer` serves your harness as an MCP server. The client can then chat with the harness, answer its approvals, and run its agents and commands.
+
+## 1. Install the MCP package
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai-harness @tanstack/ai-mcp @tanstack/ai-persistence
+vue: @tanstack/ai-harness @tanstack/ai-mcp @tanstack/ai-persistence
+solid: @tanstack/ai-harness @tanstack/ai-mcp @tanstack/ai-persistence
+svelte: @tanstack/ai-harness @tanstack/ai-mcp @tanstack/ai-persistence
+preact: @tanstack/ai-harness @tanstack/ai-mcp @tanstack/ai-persistence
+angular: @tanstack/ai-harness @tanstack/ai-mcp @tanstack/ai-persistence
+octane: @tanstack/ai-harness @tanstack/ai-mcp @tanstack/ai-persistence
+vanilla: @tanstack/ai-harness @tanstack/ai-mcp @tanstack/ai-persistence
+
+<!-- ::end:tabs -->
+
+## 2. Serve the harness on stdio
+
+Put this in `mcp.ts`. It opens sessions on your host, and reads MCP messages on stdin and writes the answers on stdout:
+
+```ts group=harness-mcp-server
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { createHarnessMcpServer } from '@tanstack/ai-mcp/harness'
+import { serveMCPStdio } from '@tanstack/ai-mcp/server/stdio'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-6.1-sol'),
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+
+export const server = await createHarnessMcpServer({
+  host,
+  harness: assistant,
+})
+
+serveMCPStdio(server)
+```
+
+For Claude Code, run this command one time:
+
+```bash
+claude mcp add --env OPENAI_API_KEY=your-key assistant -- npx tsx /path/to/mcp.ts
+```
+
+For Claude Desktop, Cursor, and other clients with a JSON file, add the same command under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "assistant": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/mcp.ts"],
+      "env": { "OPENAI_API_KEY": "your-key" }
+    }
+  }
+}
+```
+
+- Claude Desktop keeps this in `claude_desktop_config.json`.
+- Cursor keeps this in `.cursor/mcp.json`.
+
+The client starts the process when it needs the harness. The process stops when the client closes stdin. In this mode, stdout carries only MCP messages. Write your own logs with `console.error`.
+
+## 3. Use the tools
+
+Ask the client to use the harness, for example: "Ask assistant to summarize my open tickets." The client calls these tools.
+
+To talk to the harness:
+
+- `chat`: send a message and wait for the answer. While a turn runs, the message waits in the queue. To send files too, see [Send files and get media](#send-files-and-get-media).
+- `steer`: add a message to the running turn.
+- `cancel`: cancel the running turn.
+- `status`: show the status, the interrupts and questions that wait, the background agents, and the queued turns.
+
+To answer the harness:
+
+- `approve` and `reject`: answer every approval that waits.
+- `resolve`: answer every interrupt that waits, in one call.
+- `answer`: answer a question from a command or a plugin.
+
+To run what the harness has:
+
+- `agent_<name>`: one tool for each agent in `expose.agents`. It takes the agent input and returns the agent result.
+- `command_<name>`: one tool for each command in `expose.commands`. The command `connect:notion` becomes the tool `command_connect_notion`.
+
+The harness exposes nothing by default. Add the agents and commands that an MCP client can run to `expose` in `defineHarness`. See [Choose what clients can change](./connect#choose-what-clients-can-change).
+
+Two names can give the same tool name, for example `connect:notion` and `connect_notion`. Then the later one in name order gets a number: `command_connect_notion_2`. The description of each of these tools names its command or agent.
+
+Every tool takes an optional `threadId`. Each thread is its own conversation. Without a `threadId`, a tool uses the `threadId` option of the server (default `main`).
+
+`chat` answers with JSON:
+
+```json
+{
+  "status": "completed",
+  "text": "You have three open tickets.",
+  "interrupts": [],
+  "questions": []
+}
+```
+
+## Interrupts and questions
+
+A turn can stop for an interrupt. The turn then waits for your answer. Each interrupt has a `kind`:
+
+- `approval`: a tool call that needs your yes or no.
+- `client-tool`: a tool that the client runs. The turn waits for the tool output.
+- `generic`: a question from a middleware. The answer must match its `responseSchema`.
+
+For an approval, the client asks you in its own window (MCP elicitation). Answer `yes` to run the tool. Any other answer rejects it.
+
+In these cases, `chat` returns the interrupts with `status: "interrupted"`:
+
+- The client cannot ask you.
+- You close the question without an answer.
+- An interrupt of another kind also waits.
+
+```json
+{
+  "status": "interrupted",
+  "text": "Here is the plan.",
+  "interrupts": [
+    {
+      "id": "interrupt-1",
+      "kind": "generic",
+      "message": "Review the plan",
+      "responseSchema": {
+        "type": "object",
+        "properties": { "note": { "type": "string" } },
+        "required": ["note"]
+      }
+    }
+  ],
+  "questions": []
+}
+```
+
+An approval and a client tool also have `tool` and `args`, the tool call that waits.
+
+Then the client calls `approve`, `reject`, or `resolve`. That call waits for the turn to continue and returns the same JSON as `chat`. `approve` and `reject` answer approvals only. When an interrupt of another kind also waits, they refuse, and the client uses `resolve`.
+
+`resolve` takes one decision for each interrupt that waits. This example answers a turn with one approval and one generic interrupt:
+
+```json
+{
+  "decisions": [
+    { "interruptId": "approval-1", "approved": true },
+    { "interruptId": "interrupt-1", "payload": { "note": "Ship it." } }
+  ]
+}
+```
+
+- For an approval, set `approved`. `true` runs the tool, and `false` rejects it.
+- For a client tool, set `payload` to the tool output.
+- For a generic interrupt, set `payload` to a value that matches its `responseSchema`.
+
+`resolve` refuses a list that does not answer every interrupt. It also refuses a decision without the field that its kind needs.
+
+To approve every tool call without a question, set `approvals: 'auto'`. Use it only with tools that you trust. It answers approvals only, so other interrupts still come back in the result.
+
+A command or a plugin can also ask you a question. The result then has `status: "waiting"` and the question in `questions`. The client calls `answer` with the question `id` as `questionId` and your `value`. `answer` waits for the work that asked, then returns its result.
+
+## Send files and get media
+
+`chat` takes `attachments`, the files to send with the message. Each attachment is one of these:
+
+- `{ path }`: a file on the machine of the server. The file must be inside a folder that the server can read.
+- `{ url, mimeType }`: a URL that goes to the model as it is. The server does not download it. `mimeType` is optional when the URL ends in a known file extension.
+- `{ data, mimeType }`: the bytes of the file in base64.
+
+Each attachment also takes an optional `name`. This `chat` call sends a screenshot:
+
+```json
+{
+  "message": "What is wrong in this screenshot?",
+  "attachments": [{ "path": "./bug.png" }]
+}
+```
+
+The server reads a `path` only inside the `filePaths` option. By default it reads no files, so send `url` or `data`.
+
+When the work makes media, the results of `chat`, `approve`, `reject`, `resolve`, and `answer` include it:
+
+- An image or an audio file up to 5 MB comes back inline, as MCP image or audio content.
+- Any other file comes back as a `resource_link` to `harness-media://<threadId>/<id>`. The client reads the bytes with `resources/read`.
+- The JSON result lists each file in `media`, with its `id`, `kind`, `name`, `mimeType`, `size`, and `uri`.
+
+## Serve it over HTTP
+
+The server also has a `fetch` handler. Mount it on a route of your app, for example `/mcp`, and check a token first:
+
+```ts group=harness-mcp-server
+export async function handleMcp(request: Request) {
+  const token = request.headers.get('authorization')
+  if (token !== `Bearer ${process.env.MCP_TOKEN}`) {
+    return new Response('Unauthorized', { status: 401 })
+  }
+  return server.fetch(request)
+}
+```
+
+The server opens sessions with no principal. Every caller that passes your check can use every thread and its media, so give each person their own server and token.
+
+Then add it to Claude Code:
+
+```bash
+claude mcp add --transport http assistant https://your-app.example.com/mcp --header "Authorization: Bearer your-token"
+```
+
+`createHarnessMcpServer` takes these options next to `host` and `harness`:
+
+- `threadId`: the conversation of a tool call without a `threadId`. Default `main`.
+- `approvals`: `'ask'` (default) asks in the client, or returns the approvals when the client cannot ask. `'auto'` approves every tool call. Both answer approvals only.
+- `filePaths`: the folders that a `path` attachment can read from. The real path of the file, after every symlink, must be inside one of them. Default: none, so the server refuses every `path` attachment.
+- `name` and `version`: the MCP server name and version. Default: the harness name and `1.0.0`.
+
+## What you have now
+
+- Your harness in Claude Code, Claude Desktop, Cursor, or any other MCP client.
+- Approvals that the client asks you about, or answers with `approve` and `reject`.
+- Every kind of interrupt, answered with one `resolve` call.
+- The agents and commands of your harness as MCP tools.
+- Files that the client sends with a message, and the media of each turn in the result.
diff --git a/docs/harness/mcp.md b/docs/harness/mcp.md
new file mode 100644
index 0000000000..65f50ec213
--- /dev/null
+++ b/docs/harness/mcp.md
@@ -0,0 +1,221 @@
+---
+title: Use MCP servers
+id: harness-mcp
+order: 8
+description: "Connect a harness to MCP servers: a local server that runs as a process, a remote server, or Notion and Linear with an OAuth sign-in. The model gets the tools of each server, with its name as a prefix."
+keywords:
+  - tanstack ai
+  - harness
+  - mcp
+  - connectors
+  - oauth
+  - stdio
+  - notion
+  - linear
+---
+
+Your agent needs tools from MCP servers. Some servers run on your machine. Some are remote and take an API key. Notion and Linear sign in with OAuth. `mcp()` connects each server by name, and gives the model the tools of each server.
+
+This page connects your harness to MCP servers. To use your harness from an MCP client such as Claude Code, read [Use a harness from any MCP client](./mcp-server).
+
+## 1. Add the servers
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai-harness @tanstack/ai-mcp
+vue: @tanstack/ai-harness @tanstack/ai-mcp
+solid: @tanstack/ai-harness @tanstack/ai-mcp
+svelte: @tanstack/ai-harness @tanstack/ai-mcp
+preact: @tanstack/ai-harness @tanstack/ai-mcp
+angular: @tanstack/ai-harness @tanstack/ai-mcp
+octane: @tanstack/ai-harness @tanstack/ai-mcp
+vanilla: @tanstack/ai-harness @tanstack/ai-mcp
+
+<!-- ::end:tabs -->
+
+```ts group=harness-mcp
+import { defineHarness } from '@tanstack/ai-harness'
+import { mcp } from '@tanstack/ai-mcp/harness'
+import { openaiText } from '@tanstack/ai-openai'
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-6.1-sol'),
+  plugins: () => [
+    mcp({
+      servers: {
+        files: {
+          type: 'stdio',
+          command: 'npx',
+          args: ['-y', '@modelcontextprotocol/server-filesystem', '.'],
+        },
+        docs: {
+          type: 'http',
+          url: 'https://mcp.example.com/mcp',
+          headers: { authorization: `Bearer ${process.env.DOCS_TOKEN}` },
+        },
+        linear: { type: 'http', url: 'https://mcp.linear.app/mcp', oauth: true },
+      },
+    }),
+  ],
+})
+```
+
+The name of a server is the prefix of its tools. A `search` tool of the `docs` server is `docs_search` for the model.
+
+- `stdio`: the server runs as a child process on this machine (Node only). It stops when the session closes.
+- `http`: a server that speaks Streamable HTTP. Send an API key in `headers`.
+- `oauth: true`: the user signs in with `/connect linear`. See [Sign in to an OAuth server](#3-sign-in-to-an-oauth-server).
+
+## 2. Check the servers
+
+The servers connect in the background when the session opens. The first turn waits for them. Each server connects on its own, so a server that fails does not stop the tools of the others.
+
+`/mcp` shows each server and its status:
+
+```text
+files: connected (14 tools)
+docs: failed: Failed to connect to MCP server: Version negotiation probe failed: connection refused
+linear: failed: Not signed in. Run /connect linear.
+```
+
+In your own UI, read the same list from `session.snapshot().plugins['tanstack/mcp'].servers`. Each entry is an `McpServerStatus`:
+
+- `name`: the name of the server.
+- `status`: `connecting`, `connected`, or `failed`. A `failed` entry has an `error`.
+- `toolCount`: how many tools the server gives the model.
+
+## 3. Sign in to an OAuth server
+
+1. Run `/connect linear` in the CLI.
+2. The browser opens the Linear consent page. Approve it.
+3. The CLI prints `Connected to linear.`
+4. Ask for your issues. The next turn has the Linear tools.
+
+Before sign-in, the model knows that Linear is not connected. If the user asks for Linear, the model tells them to run `/connect linear`.
+
+The sign-in follows the MCP authorization spec:
+
+- The connector reads the server's OAuth metadata and registers a client for this sign-in.
+- It signs in with PKCE and a random `state`, and listens on `127.0.0.1` for one callback.
+- The token and the registered client go into `stores.credentials`. The next start of the harness uses them, so the user signs in once.
+- A new `/connect linear` replaces them. Nothing from the old sign-in stays.
+- `/disconnect linear` deletes them.
+
+Sometimes the server no longer accepts the sign-in, for example after the user removes the app in Linear. Then the turn runs without the Linear tools, and clients get a `harness.auth_required` event. The CLI prints `Sign in to linear. Run /connect linear.`, and the model tells the user to run `/connect linear`. If the server refuses the saved refresh token, the connector deletes the saved sign-in.
+
+The model never sees the token. To keep sign-ins after a restart, give the host a credential store. [Auth and connectors](./auth) shows one. With `oauth: true`, `headers` and `authProvider` do not apply.
+
+## Choose which tools ask first
+
+- A tool of an `oauth: true` server asks for approval before it runs, unless the server marks it read-only.
+- The tools of the other servers run without a question.
+
+## Answer a question from a server
+
+An MCP server can ask the user for input in the middle of a tool call. MCP calls this elicitation. The session asks the user, and the tool call waits for the answer.
+
+- A form request becomes a question with the `message` and the requested `schema`.
+- A URL request becomes a question with a `url`. The user opens the page, then answers. The session does not open the page.
+- `mcp()` and `mcpConnector` both ask this way, for servers on MCP spec 2025 and on spec 2026-07-28.
+- One tool call can ask more than once. On spec 2026-07-28, one call can ask up to 5 times. One more request fails the tool call.
+
+Answer with `session.answer({ questionId, value })`, or from a [`HarnessClient`](./connect). The value tells the server what the user did:
+
+| Value | The server gets |
+| --- | --- |
+| The form content, for example `{ city: 'Paris' }` | `accept` with that content |
+| Any other value, for a URL request | `accept` |
+| `{ action: 'decline' }` | `decline` |
+| `{ action: 'cancel' }` | `cancel` |
+
+This code answers the first open question with a city:
+
+```ts group=harness-mcp
+import type { HarnessSession } from '@tanstack/ai-harness'
+
+export async function answerCity(session: HarnessSession) {
+  const [question] = session.snapshot().pendingQuestions
+  if (question) {
+    await session.answer({
+      questionId: question.questionId,
+      value: { city: 'Paris' },
+    })
+  }
+}
+```
+
+## Set a time limit
+
+`timeoutMs` limits how long one server can take to connect, to send its tool list, and to answer each tool call:
+
+```ts group=harness-mcp
+export const quick = mcp({
+  servers: {
+    docs: { type: 'http', url: 'https://mcp.example.com/mcp', timeoutMs: 10_000 },
+  },
+})
+```
+
+- The default is the MCP SDK default, 60 seconds.
+- A server that is too slow gets the status `failed`. The tools of the other servers still work.
+- If a server does not connect in time, its open request closes, or its child process stops.
+- A `stdio` server can take up to two times `timeoutMs` to connect. When the version check runs out of time, the SDK tries the older handshake, with its own `timeoutMs`.
+
+An `http` server that does not connect in time shows this in `/mcp`:
+
+```text
+docs: failed: Failed to connect to MCP server: Version negotiation probe timed out after 10000ms
+```
+
+## One OAuth server with more options
+
+`mcpConnector` adds one OAuth server, with options that `mcp()` does not have. The sign-in works as in [step 3](#3-sign-in-to-an-oauth-server):
+
+```ts group=harness-mcp
+import { mcpConnector } from '@tanstack/ai-mcp/connector'
+
+export const linearWithoutWrites = mcpConnector({
+  id: 'linear',
+  label: 'Linear',
+  url: 'https://mcp.linear.app/mcp',
+  // Ask before every tool whose name starts with "save".
+  needsApproval: (tool) => tool.name.startsWith('save'),
+})
+```
+
+Add it to the plugins like any plugin: `plugins: () => [linearWithoutWrites]`. The CLI then prints `Connected to Linear.`, with the `label`.
+
+- `needsApproval`: which tools ask first. Default: every tool that the server does not mark read-only.
+- `prefix`: the tool name prefix. Default: the `id`.
+- `scopes`: the OAuth scopes to ask for. Default: what the server offers.
+- `clientName`: the app name on the consent page. Default: `TanStack AI Harness`.
+
+## Tools that appear later
+
+A plugin can give tools that it finds at run time, like the tools of a server that the user signed in to after the session started. Return them from `discoverTools`. The session asks each plugin before every turn:
+
+```ts group=harness-mcp
+import { definePlugin } from '@tanstack/ai-harness'
+import type { AnyTool } from '@tanstack/ai'
+
+const found: Array<AnyTool> = []
+
+export const lateTools = definePlugin({
+  name: 'acme/late-tools',
+  setup: () => ({
+    discoverTools: () => found,
+  }),
+})
+```
+
+- A tool whose name is already taken is skipped. The first tool keeps the name.
+- If `discoverTools` throws, the turn runs without that plugin's tools, and clients get a `harness.plugin.warning` event.
+
+## What you have now
+
+- Tools from local, remote, and OAuth MCP servers, with the server name as a prefix.
+- A status for each server, in `/mcp` and in your UI.
+- One browser sign-in per service, kept in your credential store.
+- A question before the tools that change data.
+- Server requests for input, asked as session questions.
diff --git a/docs/harness/media.md b/docs/harness/media.md
index d11fd21710..0c4b95b161 100644
--- a/docs/harness/media.md
+++ b/docs/harness/media.md
@@ -182,3 +182,5 @@ If a store is missing, the host keeps media in memory. `memoryPersistence()` has
 - Media from your agents, saved with no change to the agent code.
 - Limits, and a clear error when the model cannot read a file.
 - Media that stays after a restart.
+
+Next: show media in your own screen with [Build your own UI](./custom-ui#show-media).
diff --git a/docs/harness/plugins.md b/docs/harness/plugins.md
index 01724f30ee..0abe132a0d 100644
--- a/docs/harness/plugins.md
+++ b/docs/harness/plugins.md
@@ -115,7 +115,7 @@ export const macros = definePlugin({
 
 - `ctx.commands.set(name, command)` adds a command of this plugin, or replaces it. A name that another plugin owns throws.
 - `ctx.commands.delete(name)` removes a command of this plugin. Another plugin's name does nothing.
-- Each change sends a `harness.commands.changed` event, so a client can read `session.commands()` again.
+- Each change sends a `harness.commands.changed` event, so a client can read `session.commands()` again. A [session view](./custom-ui) reads the new list by itself.
 - During `setup`, wait for `ctx.commands.ready` before you call `has` or `set`. The plugins after this one add their commands later, so a name can look free and still be taken.
 
 ```ts group=harness-plugins
@@ -250,8 +250,8 @@ The `turn` has these fields:
 | `operationId` | The id of the operation that runs the turn. |
 | `inputId` | The id of the input, when the turn has one. |
 | `message` | The user message of the input. `undefined` for a resolve and a continue. |
-| `context` | The `context` of the input. It is client data, so do not trust it. |
-| `principal` | Who sent the input. Default: the principal that opened the session. |
+| `context` | The [context of the input](./inputs#send-context-with-a-message). It is client data, so do not trust it. |
+| `principal` | Who sent the input. Default: the principal that opened the session. See [Share a thread](./shared-threads). |
 | `overrides` | The [overrides of the prompt](./turn-control#give-one-prompt-its-own-settings), when it has some. |
 
 The session uses the picks like this:
diff --git a/docs/harness/shared-threads.md b/docs/harness/shared-threads.md
new file mode 100644
index 0000000000..761d08ad88
--- /dev/null
+++ b/docs/harness/shared-threads.md
@@ -0,0 +1,199 @@
+---
+title: Share a thread between people
+id: harness-shared-threads
+order: 7
+description: "Let several people write in one thread. Each message runs as its sender, with the credentials and the provider key of that person."
+keywords:
+  - tanstack ai
+  - harness
+  - shared thread
+  - principal
+  - tenantId
+  - canJoin
+---
+
+Several people write in one thread: a team in one chat, or a customer and a support agent. A message from Bob must run as Bob. His GitHub token and his provider key must do the work, not those of the person who opened the thread first. The harness runs each message as the person who sent it.
+
+## 1. Return the sender from `authorize`
+
+`authorize` decides who sends each request. Each message runs as the principal that it returns. If your users belong to organizations, add `tenantId`:
+
+```ts group=harness-shared-threads
+import {
+  createHarnessHandler,
+  createHarnessHost,
+  defineHarness,
+} from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { openaiText } from '@tanstack/ai-openai'
+
+export const assistant = defineHarness({
+  name: 'acme/assistant',
+  adapter: openaiText('gpt-6.1-sol'),
+})
+
+const host = createHarnessHost({ persistence: memoryPersistence() })
+
+// Your own lookups: a session token to a user, and a thread to its members.
+const users = new Map([
+  ['Bearer token-ada', { id: 'ada', tenantId: 'acme' }],
+  ['Bearer token-bob', { id: 'bob', tenantId: 'acme' }],
+])
+const members = new Map([['team-thread', ['ada', 'bob']]])
+
+export const handler = createHarnessHandler({
+  host,
+  harness: assistant,
+  authorize: (request) => users.get(request.headers.get('authorization') ?? '') ?? null,
+  canAccess: (principal, threadId) =>
+    members.get(threadId)?.includes(principal.id) ?? false,
+})
+```
+
+You pass nothing else. The sender of each request is used everywhere:
+
+- The log keeps the sender of each message. After a restart, a message runs again as its sender.
+- The tools of a turn get the credentials of the sender, in `ctx.credentials`.
+- The model call uses the provider key of the sender, in `ctx.keys`. So the sender pays for the call.
+- In a plugin, `ctx.session.principal` is the sender of the running turn. Outside a turn, it is the person who opened the session first.
+- Commands, for example `connect:github`, run as their sender. So a sign-in belongs to the person who signed in. A turn that waits for a sign-in continues only when its own sender signs in.
+
+`handleHarnessSocket` works the same way. Every input on the socket runs as the `principal` that you give it. Context that a client sends with a message is client data, and it never changes the sender. See [Send context with a message](./inputs#send-context-with-a-message).
+
+## 2. Connect each person
+
+Each person opens the same thread with their own token. This snippet shows two clients. In a real app, each person has one client in their own browser:
+
+```ts group=harness-shared-threads-client
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import type { assistant } from './harness'
+
+const ada = createHarnessClient<typeof assistant>({
+  url: '/api/harness',
+  threadId: 'team-thread',
+  headers: { authorization: 'Bearer token-ada' },
+})
+const bob = createHarnessClient<typeof assistant>({
+  url: '/api/harness',
+  threadId: 'team-thread',
+  headers: { authorization: 'Bearer token-bob' },
+})
+
+await ada.prompt('Open an issue for the login bug.')
+await bob.prompt('List my open pull requests.')
+```
+
+Bob sends his message while the turn of Ada runs. His message waits. Then it runs as its own turn, as Bob.
+
+On the server, give the sender to `prompt` yourself. `steer`, `followUp`, `resolve`, and `command` take `principal` too. Without it, the message runs as the person who opened the session:
+
+```ts group=harness-shared-threads
+const session = await host.open(assistant, { threadId: 'team-thread' })
+const ada = { id: 'ada', tenantId: 'acme' }
+
+session.prompt('Summarize the open issues.', { principal: ada })
+session.command('connect:github', undefined, { principal: ada })
+```
+
+A command acts for the person who runs it. In its `run` context, `session.principal` is that person, and `session.prompt` runs as that person.
+
+If you write a command that saves a sign-in or a key, save it with the `credentials` of the second `run` argument. Those credentials belong to the person who runs the command. The `ctx.credentials` of `setup` belong to the sender of the running turn:
+
+```ts group=harness-shared-threads
+import { defineCommand, definePlugin } from '@tanstack/ai-harness'
+import { z } from 'zod'
+
+export const linearKey = definePlugin({
+  name: 'acme/linear-key',
+  setup: () => ({
+    commands: {
+      'connect:linear': defineCommand({
+        description: 'Save a Linear API key',
+        input: z.object({ key: z.string() }),
+        run: async ({ key }, { credentials }) => {
+          await credentials.set({
+            id: 'linear',
+            credential: { type: 'api_key', value: key },
+          })
+          return 'Connected to Linear.'
+        },
+      }),
+    },
+  }),
+})
+```
+
+## 3. Keep other people out of a running turn
+
+A message with `busy: 'steer'` can join the turn that runs now. A joined message runs with the credentials of the sender of that turn. So without `turn.canJoin`, a waiting message joins the running turn only when the same person sent both:
+
+- A message from another person waits. It runs as its own turn after the running one, as its sender.
+- The waiting messages join as a prefix, in the order they arrived. So a message that waits also holds back the messages that wait after it.
+
+Set `canJoin` to choose your own rule. It gets the sender of the waiting message as `principal`, and the sender of the running turn as `turnPrincipal`. This harness keeps the default rule, and it also lets your build bot join any turn:
+
+```ts group=harness-shared-threads
+export const team = defineHarness({
+  name: 'acme/team',
+  adapter: openaiText('gpt-6.1-sol'),
+  turn: {
+    canJoin: ({ principal, turnPrincipal }) =>
+      principal?.id === 'build-bot' ||
+      (principal?.id === turnPrincipal?.id &&
+        principal?.tenantId === turnPrincipal?.tenantId),
+  },
+})
+```
+
+A background agent that a turn starts keeps the provider key of the sender of that turn. It keeps the key also after the turn ends. The wake turn after the agent runs as the person who started the agent.
+
+One limit applies to code that runs after its turn ended, for example a tool of a background agent. That code reads `ctx.credentials` and `ctx.session.principal` of the turn that runs at that time. In an agent, use `ctx.keys`. In a command, use the `credentials` of its `run` context.
+
+## 4. Keep organizations apart
+
+The credential scope of a turn has the `userId` and the `tenantId` of the sender. So one person in two organizations has two sets of credentials. The memory store of `memoryPersistence()` keeps them apart. In your own credential store, put `scope.tenantId` in the key:
+
+```ts group=harness-shared-threads
+import type { Scope } from '@tanstack/ai'
+
+export const keyOf = (scope: Scope, id: string) =>
+  `${scope.tenantId ?? '-'}:${scope.userId ?? '-'}:${id}`
+```
+
+Use `keyOf` in `get`, `set`, `delete`, and `list` of the store in [Keep credentials](./auth#keep-credentials).
+
+### Share one credential with the whole organization
+
+Some services have one key for the whole organization, for example a company account. Save that key once, with no `userId`. Every user of the tenant can then use it:
+
+```ts group=harness-shared-threads
+import type { CredentialStore } from '@tanstack/ai-persistence'
+
+// Your admin code. A credential without a userId belongs to the tenant.
+export async function shareKey(
+  store: CredentialStore,
+  tenantId: string,
+  value: string,
+) {
+  await store.set({
+    scope: { threadId: 'admin', tenantId },
+    id: 'linear',
+    credential: { type: 'api_key', value },
+  })
+}
+```
+
+The store keys credentials by user and tenant, so the `threadId` of this scope has no effect.
+
+- A turn reads the credential of its sender first. If the sender has none, the turn reads the credential of the tenant.
+- A save from a turn goes to the sender only. This includes `connect:<id>` and `ctx.credentials.set`. The credential of the tenant does not change.
+- `ctx.credentials.list()` shows the credentials of the sender and of the tenant. For the same id, the credential of the sender wins.
+- Use an API key for a credential of the tenant. If the turn refreshes an OAuth token of the tenant, the new token goes to the sender only.
+
+## What you have now
+
+- Each message runs as the person who sent it, also after a restart.
+- Tools and model calls use the credentials and the provider key of the sender.
+- A message from another person waits for its own turn.
+- Sign-ins and keys belong to the person who saved them.
+- The credentials of two organizations stay apart, and one key can serve a whole organization.
diff --git a/docs/harness/subagents.md b/docs/harness/subagents.md
index feeb1421c9..82edee1ce7 100644
--- a/docs/harness/subagents.md
+++ b/docs/harness/subagents.md
@@ -63,7 +63,7 @@ export const review = definePlugin({
 - `ctx.agents.start(agent, input, { wake: true })` runs it in the background and starts a turn when it finishes or fails.
 - `ctx.agents.group(options, body)` runs several. With `onFailure: 'cancel-siblings'`, one failure cancels the others. With `'collect'`, use `group.runSettled` to get every result or error. Every child settles before `group` returns.
 
-The turn that `wake: true` starts sends the model a user message from the harness, for example `Background agent pricer finished: ...`. The user did not write it. So the transcript marks it with `metadata.harness.wake: true`. In your chat UI, skip the user messages with this mark.
+The turn that `wake: true` starts sends the model a user message from the harness, for example `Background agent pricer finished: ...`. The user did not write it. So the transcript marks it with `metadata.harness.wake: true`, and a view from `createSessionView` does not show it. In your own chat UI, skip the user messages with this mark.
 
 To track usage or apply a policy in each of these runs, see [Middleware in every agent](./plugins#middleware-in-every-agent).
 
@@ -178,6 +178,8 @@ A steer joins only a run of the same sender. A steer from another sender runs as
 
 An agent written as plain code, with no `ctx.chat` call, makes no model call. It gets a steer only as a follow-up.
 
+To message a run from the browser, see [Send a message to a running agent](./connect#send-a-message-to-a-running-agent).
+
 ### Find a run by its id
 
 Your server often has only the id of a run, for example from a button in the UI. Use the session:
@@ -348,6 +350,23 @@ What you get back:
 - A child that failed before it wrote anything gives you one empty message. It holds only the card, so you can still show that it failed.
 - A nested child works the same way. Pass its own `subagentRunId`.
 
+In the browser, `client.agentTranscript` reads the same messages through [your handler](./connect):
+
+```ts group=harness-subagents-transcript-client
+import { createHarnessClient } from '@tanstack/ai-harness/client'
+import type { studio } from './harness'
+
+const client = createHarnessClient<typeof studio>({
+  url: '/api/harness',
+  threadId: 'user-1-thread',
+  headers: { authorization: 'Bearer my-token' },
+})
+
+export async function childMessages(subagentRunId: string) {
+  return client.agentTranscript(subagentRunId)
+}
+```
+
 You get an empty list when the id is unknown, or when the child belongs to another thread. The id can come from a prompt, so a session never reads the children of another thread. A [fork](./fork-and-reset) copies the agent results, but their children stay with the thread that ran them. So in the fork, `agentTranscript` gives an empty list for them.
 
 ## Route a turn to an agent
diff --git a/docs/harness/thread-settings.md b/docs/harness/thread-settings.md
index f4c9867f18..9de666b134 100644
--- a/docs/harness/thread-settings.md
+++ b/docs/harness/thread-settings.md
@@ -70,6 +70,8 @@ An unknown field, model, or plugin, or a bad value, gets a receipt with `status:
 
 `configure` is an input, so the log keeps who changed what. Each change sends a `harness.settings.changed` event with the new `settings`.
 
+A client can change only the fields in `expose.settings` of the harness. See [Choose what clients can change](./connect#choose-what-clients-can-change).
+
 ## 3. Build a model menu
 
 `session.describe()` returns the stored `settings` and the names of the `models`, so a UI can build a menu:
diff --git a/docs/harness/turn-control.md b/docs/harness/turn-control.md
index a88545c6f7..77ea191213 100644
--- a/docs/harness/turn-control.md
+++ b/docs/harness/turn-control.md
@@ -83,7 +83,7 @@ const reminded = defineHarness({
 - The transcript, the session log, and the message store never keep them.
 - A return with only `ephemeral` messages also sends the model back to work, and it counts for `maxFinishCycles`.
 - `onJoin` can return `ephemeral` messages too. They go to the model call of the join.
-- A reminder that you send in your own loop, one turn at a time, does not count for `maxFinishCycles`. Pass it as `ephemeral` to `prompt` or `continue`. Each model call of that turn gets it, and no store keeps it.
+- A reminder that you send in your own loop, one turn at a time, does not count for `maxFinishCycles`. Pass it as `ephemeral` to `prompt` or `continue`. Each model call of that turn gets it, and no store keeps it. See [Give the model a note for one turn](./inputs#give-the-model-a-note-for-one-turn).
 
 ## Retry model errors
 
@@ -191,7 +191,7 @@ The join stops at the first message that:
 
 That message and the ones after it wait. `canJoin` runs again before each model call and at each final answer, so it can run more than once for one message. Keep it a quick check with no side effects. What still waits when the turn ends runs as its own turn, before other queued turns. A cancelled one settles `aborted` and does not run.
 
-A joined message runs with the credentials of the sender of the turn. So without `turn.canJoin`, a waiting message joins the running turn only when the same person sent both. A message from another person waits and runs as its own turn after the running one, as its sender. Joins are a prefix, so it also holds back the messages that wait after it. Set `canJoin` to choose your own rule. Compare `principal` with `turnPrincipal` to keep one person's message out of another person's turn.
+A joined message runs with the credentials of the sender of the turn. So without `turn.canJoin`, a waiting message joins the running turn only when the same person sent both. A message from another person waits and runs as its own turn after the running one, as its sender. Joins are a prefix, so it also holds back the messages that wait after it. Set `canJoin` to choose your own rule. Compare `principal` with `turnPrincipal` to keep one person's message out of another person's turn. See [Keep other people out of a running turn](./shared-threads#3-keep-other-people-out-of-a-running-turn).
 
 `onJoin` runs before the model call that the joined messages reach. It can return messages, which come after the joined ones, and records, which land in the same append as the join. Records need a durable host.
 
diff --git a/docs/harness/usage.md b/docs/harness/usage.md
index c6643e4a88..507cba0c9c 100644
--- a/docs/harness/usage.md
+++ b/docs/harness/usage.md
@@ -55,7 +55,7 @@ At the end of each call, the provider reports its usage. These calls count:
 - The subagents that a turn starts, for the same sender.
 - Background agents, for the person who started the agent.
 
-A call that fails before it ends does not count. Each message runs as its sender, so in a thread that several people use, `bySender` shows what each person used.
+A call that fails before it ends does not count. Each message runs as its sender, so in a [shared thread](./shared-threads), `bySender` shows what each person used.
 
 ## Where the totals live
 
diff --git a/examples/ts-code-mode-web/package.json b/examples/ts-code-mode-web/package.json
index 74fae64e3e..970f1fa451 100644
--- a/examples/ts-code-mode-web/package.json
+++ b/examples/ts-code-mode-web/package.json
@@ -35,7 +35,7 @@
     "@tanstack/react-router": "^1.170.41",
     "@tanstack/react-start": "^1.168.60",
     "@tanstack/router-plugin": "^1.168.42",
-    "@tanstack/store": "^0.8.0",
+    "@tanstack/store": "^0.11.1",
     "framer-motion": "^11.15.0",
     "highlight.js": "^11.11.1",
     "isolated-vm": "^6.0.2",
diff --git a/examples/ts-react-chat/package.json b/examples/ts-react-chat/package.json
index 2298bab671..3ce3a7f02d 100644
--- a/examples/ts-react-chat/package.json
+++ b/examples/ts-react-chat/package.json
@@ -56,7 +56,7 @@
     "@tanstack/react-start": "^1.168.60",
     "@tanstack/react-store": "^0.8.0",
     "@tanstack/router-plugin": "^1.168.42",
-    "@tanstack/store": "^0.8.0",
+    "@tanstack/store": "^0.11.1",
     "dockerode": "^4.0.2",
     "highlight.js": "^11.11.1",
     "lucide-react": "^0.561.0",
diff --git a/examples/ts-solid-chat/package.json b/examples/ts-solid-chat/package.json
index d47ee58d31..5c031cf2f3 100644
--- a/examples/ts-solid-chat/package.json
+++ b/examples/ts-solid-chat/package.json
@@ -28,7 +28,7 @@
     "@tanstack/solid-router-ssr-query": "^1.139.10",
     "@tanstack/solid-start": "^1.168.57",
     "@tanstack/solid-store": "^0.8.0",
-    "@tanstack/store": "^0.8.0",
+    "@tanstack/store": "^0.11.1",
     "highlight.js": "^11.11.1",
     "lucide-solid": "^0.554.0",
     "solid-js": "^1.9.10",
diff --git a/packages/ai-harness/package.json b/packages/ai-harness/package.json
index 5d45fa9b9d..3f1f225ee5 100644
--- a/packages/ai-harness/package.json
+++ b/packages/ai-harness/package.json
@@ -29,6 +29,14 @@
     ".": {
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js"
+    },
+    "./client": {
+      "types": "./dist/esm/client.d.ts",
+      "import": "./dist/esm/client.js"
+    },
+    "./view": {
+      "types": "./dist/esm/view/index.d.ts",
+      "import": "./dist/esm/view/index.js"
     }
   },
   "scripts": {
@@ -42,6 +50,9 @@
     "test:lib:dev": "pnpm test:lib --watch",
     "test:types": "tsc"
   },
+  "dependencies": {
+    "@tanstack/store": "^0.11.1"
+  },
   "devDependencies": {
     "@tanstack/ai": "workspace:*",
     "@tanstack/ai-persistence": "workspace:*",
diff --git a/packages/ai-harness/src/client.ts b/packages/ai-harness/src/client.ts
new file mode 100644
index 0000000000..d171f990bb
--- /dev/null
+++ b/packages/ai-harness/src/client.ts
@@ -0,0 +1,599 @@
+// Browser-safe: this module has type-only imports from the rest of the
+// package, plus `media-ref`, which has type-only imports itself. So no server
+// code (adapters, stores, secrets) reaches a client.
+import { isMediaRecord } from './media-ref'
+import type { ModelMessage, RunAgentResumeItem } from '@tanstack/ai'
+import type {
+  SessionIndexEntry,
+  SessionIndexPage,
+} from '@tanstack/ai-persistence'
+import type { AgentInputOf } from './agents'
+import type { AnyHarness, HarnessAgentsOf, SessionMetadataOf } from './define'
+import type { HostEvent } from './host'
+import type { SessionDescription, SessionSnapshot } from './session/index'
+import type { SessionEntryChange } from './session-entry'
+import type {
+  BusyPolicy,
+  Cursor,
+  ForkPoint,
+  HarnessInput,
+  MediaRecord,
+  Receipt,
+  SessionEvent,
+  ThreadSettingsChange,
+  UserInput,
+  WaitingInput,
+} from './types'
+
+export {
+  MEDIA_URL_PREFIX,
+  kindOf,
+  mediaIdOf,
+  mediaOfMessage,
+  mediaPart,
+} from './media-ref'
+export type { ForkPoint, MediaKind, MediaRecord } from './types'
+export type {
+  HostEvent,
+  HostSessionDeletedEvent,
+  HostSessionEvent,
+  HostStatusEvent,
+} from './host'
+
+export interface HarnessClientOptions {
+  /** The base URL of `createHarnessHandler`, for example `/api/harness`. */
+  url: string
+  threadId: string
+  /** Extra headers, for example `Authorization`. */
+  headers?: Record<string, string> | (() => Record<string, string>)
+  fetch?: typeof fetch
+  /** Wait before a reconnect of `events()`. Default 1000 ms. */
+  reconnectDelayMs?: number
+}
+
+type StartArgs<TAgent> =
+  AgentInputOf<TAgent> extends undefined
+    ? [input?: undefined, options?: { detached?: boolean }]
+    : [input: AgentInputOf<TAgent>, options?: { detached?: boolean }]
+
+/** `client.agents`: start an exposed agent, typed from the harness. */
+export type ClientAgentHandles<THarness> = {
+  [TAgent in HarnessAgentsOf<THarness> as TAgent['name']]: {
+    start: (...args: StartArgs<TAgent>) => Promise<Receipt>
+  }
+}
+
+export interface HarnessClient<THarness extends AnyHarness> {
+  /**
+   * Send a prompt. `inputId` is an id you choose: a retry with the same id
+   * and message gets the first receipt and does not run again. `ephemeral`
+   * are messages for the model calls of this turn only. See
+   * `session.prompt`.
+   */
+  prompt: (
+    message: UserInput,
+    options?: {
+      busy?: BusyPolicy
+      inputId?: string
+      ephemeral?: ReadonlyArray<ModelMessage & { role: 'user' }>
+    },
+  ) => Promise<Receipt>
+  steer: (
+    message: UserInput,
+    options?: { inputId?: string },
+  ) => Promise<Receipt>
+  followUp: (
+    message: UserInput,
+    options?: { inputId?: string },
+  ) => Promise<Receipt>
+  /**
+   * Start a turn from the stored transcript, with no new message. See
+   * `session.continue`.
+   */
+  continue: (options?: {
+    inputId?: string
+    ephemeral?: ReadonlyArray<ModelMessage & { role: 'user' }>
+  }) => Promise<Receipt>
+  resolve: (resume: Array<RunAgentResumeItem>) => Promise<Receipt>
+  cancel: (operationId?: string) => Promise<Receipt>
+  /**
+   * Cancel an input that waits (see `snapshot().waitingInputs`). An input
+   * that started is refused with `not_waiting`: use `cancel`.
+   */
+  cancelInput: (inputId: string) => Promise<Receipt>
+  /**
+   * Move an input that waits: `'steer'` joins the running turn, `'queue'`
+   * runs it as its own turn later.
+   */
+  setDelivery: (change: {
+    inputId: string
+    delivery: WaitingInput['delivery']
+  }) => Promise<Receipt>
+  agents: ClientAgentHandles<THarness>
+  /** Answer a question from a command or a plugin. */
+  answer: (answer: { questionId: string; value: unknown }) => Promise<Receipt>
+  /** Run a plugin command. Its result arrives as a `harness.command.result` event. */
+  command: (name: string, input?: unknown) => Promise<Receipt>
+  /** Change a session setting. */
+  setConfig: (change: { key: string; value: unknown }) => Promise<Receipt>
+  /** Change the stored settings of the thread. See `session.configure`. */
+  configure: (settings: ThreadSettingsChange) => Promise<Receipt>
+  /**
+   * Start a fresh model context from the next turn. The model sees `note`
+   * first, when you give one. The transcript keeps every message.
+   */
+  reset: (note?: string, options?: { inputId?: string }) => Promise<Receipt>
+  /**
+   * Go back to the message `messageId`, as `session.revert` does. The
+   * harness must list `'undo'` in `expose.commands`.
+   */
+  revert: (messageId: string) => Promise<Receipt>
+  /** End the revert that stands, as `session.unrevert` does. */
+  unrevert: () => Promise<Receipt>
+  /**
+   * Send a message to the agent run `operationId`, as `AgentRun.send`
+   * does. The harness must list the run's agent in `expose.agents`.
+   */
+  sendToAgent: (options: {
+    operationId: string
+    message: UserInput
+    mode?: 'steer' | 'followUp'
+    inputId?: string
+  }) => Promise<Receipt>
+  /**
+   * The session events from `from` (exclusive). Reconnects after a network
+   * error and resumes from the last cursor. Ends when `signal` aborts.
+   * `onConnection` reports `'open'` for each connection and `'reconnecting'`
+   * before each new try.
+   */
+  events: (options?: {
+    from?: Cursor
+    signal?: AbortSignal
+    onConnection?: (state: 'open' | 'reconnecting') => void
+  }) => AsyncIterable<SessionEvent>
+  /**
+   * The status changes and the session changes of all your sessions on the
+   * server (`host.events()`). First the current status of each open session.
+   * It ends when `signal` aborts or the server closes the stream. Call it
+   * again to reconnect: the current statuses come first again.
+   */
+  hostEvents: (options?: { signal?: AbortSignal }) => AsyncIterable<HostEvent>
+  snapshot: () => Promise<SessionSnapshot>
+  /** The saved messages of the thread. */
+  transcript: () => Promise<Array<ModelMessage>>
+  /**
+   * The saved messages of a child agent run of the thread, by its
+   * `subagentRunId`. Empty for an unknown id. A child with no messages has
+   * one message with no content, with its card. See `session.agentTranscript`.
+   */
+  agentTranscript: (subagentRunId: string) => Promise<Array<ModelMessage>>
+  /**
+   * The commands, settings, and tools of the session. Only the commands in
+   * `expose.commands` and the config keys in `expose.config`.
+   */
+  describe: () => Promise<SessionDescription>
+  /**
+   * Store a file in the media store of the thread. Send the record in a
+   * prompt with `mediaPart(record)`. Throws when the handler refuses the
+   * file, for example `413` for a file over the size limit.
+   */
+  upload: (
+    body: Blob | ArrayBuffer | Uint8Array,
+    info: { name: string; mimeType: string },
+  ) => Promise<MediaRecord>
+  /**
+   * A signed URL for a media file, for `<img>`, `<audio>`, or `<video>`. It
+   * stops working at `expiresAt` (epoch milliseconds). Ask again for a new one.
+   */
+  mediaUrl: (id: string) => Promise<{ url?: string; expiresAt?: number }>
+  /** The bytes of a media file. */
+  loadMedia: (id: string) => Promise<Uint8Array>
+  /**
+   * One page of your sessions, newest first. Default: top-level sessions.
+   * Pass `parentThreadId` to get the child sessions of a thread, and the
+   * `cursor` of a page to get the next page. `search` keeps the sessions
+   * whose title contains the text, without case. `metadata` keeps the
+   * sessions with each exact metadata value.
+   */
+  listSessions: (options?: {
+    limit?: number
+    cursor?: string
+    parentThreadId?: string
+    search?: string
+    metadata?: Record<string, string>
+  }) => Promise<
+    Omit<SessionIndexPage, 'entries'> & {
+      entries: Array<SessionIndexEntry<SessionMetadataOf<THarness>>>
+    }
+  >
+  /** Set the title of one of your sessions. Resolves to the changed entry. */
+  renameSession: (change: {
+    threadId: string
+    title: string
+  }) => Promise<SessionIndexEntry<SessionMetadataOf<THarness>>>
+  /**
+   * Change the `title`, `pinned`, or `metadata` of one of your sessions, for
+   * example the context items a user pinned in the composer. Each field you
+   * pass besides `threadId` replaces the stored one. The harness `metadataSchema` checks
+   * `metadata` on the server. Resolves to the changed entry.
+   */
+  updateSession: (
+    change: { threadId: string } & SessionEntryChange<
+      SessionMetadataOf<THarness>
+    >,
+  ) => Promise<SessionIndexEntry<SessionMetadataOf<THarness>>>
+  /**
+   * Remove one of your sessions from the session index. The transcript and
+   * the other data of the thread stay on the server.
+   */
+  deleteSession: (threadId: string) => Promise<void>
+  /**
+   * Copy one of your sessions into a new session, up to a message id.
+   * Resolves to the entry of the new session.
+   */
+  forkSession: (options: {
+    threadId: string
+    at: ForkPoint
+  }) => Promise<SessionIndexEntry<SessionMetadataOf<THarness>>>
+}
+
+/** The body of `POST sessions`. */
+type SessionChange =
+  | { op: 'rename'; threadId: string; title: string }
+  | ({ op: 'update'; threadId: string } & SessionEntryChange<unknown>)
+  | { op: 'delete'; threadId: string }
+  | ({ op: 'fork'; threadId: string } & ForkPoint)
+
+/** The `data` of each event of an SSE body, as parsed JSON. */
+async function* sseFrames(
+  body: ReadableStream<Uint8Array>,
+  signal: AbortSignal | undefined,
+) {
+  const reader = body.getReader()
+  // Some fetch shims ignore the signal once the body streams.
+  signal?.addEventListener('abort', () => void reader.cancel(), {
+    once: true,
+  })
+  const decoder = new TextDecoder()
+  let buffer = ''
+  try {
+    while (true) {
+      const { value, done } = await reader.read()
+      if (done) return
+      buffer += decoder.decode(value, { stream: true })
+      const blocks = buffer.split('\n\n')
+      buffer = blocks.pop() ?? ''
+      for (const block of blocks) {
+        const data = block
+          .split('\n')
+          .find((line) => line.startsWith('data: '))
+          ?.slice(6)
+        if (!data) continue
+        const frame: unknown = JSON.parse(data)
+        yield frame
+      }
+    }
+  } finally {
+    // A reader that stops early closes the connection, so the server stops.
+    reader.cancel().catch(() => {})
+  }
+}
+
+// The answer of `GET media-url`: a signed path, relative to the base URL.
+function isSignedPath(
+  value: unknown,
+): value is { path: string; expiresAt: number } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'path' in value &&
+    typeof value.path === 'string' &&
+    'expiresAt' in value &&
+    typeof value.expiresAt === 'number'
+  )
+}
+
+/**
+ * A client for a harness session served by `createHarnessHandler`. Pass the
+ * harness type for typed agents: `createHarnessClient<typeof studio>(...)`.
+ * Import the harness with `import type`, so it stays out of the bundle.
+ */
+export function createHarnessClient<THarness extends AnyHarness>(
+  options: HarnessClientOptions,
+): HarnessClient<THarness> {
+  const base = options.url.replace(/\/$/, '')
+  const doFetch = options.fetch ?? fetch
+  const headers = () =>
+    typeof options.headers === 'function'
+      ? options.headers()
+      : (options.headers ?? {})
+
+  // The handler answers a refusal with `{ error }`. Any other body falls
+  // back to the status text.
+  const failure = (action: string, response: Response, body: unknown) => {
+    const message =
+      typeof body === 'object' && body !== null && 'error' in body
+        ? String(body.error)
+        : response.statusText
+    return new Error(
+      `Harness ${action} failed (${response.status}): ${message}`,
+    )
+  }
+
+  // The response when it is a success. Else it throws with the `{ error }`
+  // of the handler.
+  const checked = async (action: string, response: Response) => {
+    if (response.ok) return response
+    // A proxy can refuse a request with a page, not JSON.
+    const refusal: unknown = await response.json().catch(() => undefined)
+    throw failure(action, response, refusal)
+  }
+
+  const send = async (input: HarnessInput): Promise<Receipt> => {
+    const response = await doFetch(`${base}/control`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers() },
+      body: JSON.stringify({ threadId: options.threadId, input }),
+    })
+    const body: unknown = await (await checked('request', response)).json()
+    // The handler answers /control with a Receipt.
+    return body as Receipt
+  }
+
+  const get = async (route: string, params: Record<string, string> = {}) => {
+    const query = new URLSearchParams({ threadId: options.threadId, ...params })
+    const response = await doFetch(`${base}/${route}?${query}`, {
+      headers: headers(),
+    })
+    if (!response.ok)
+      throw new Error(`Harness ${route} failed (${response.status})`)
+    return response
+  }
+
+  const read = async <T>(route: string, params?: Record<string, string>) =>
+    // Each GET route answers with the type of the `HarnessClient` member
+    // that reads it. That member type sets `T`.
+    (await (await get(route, params)).json()) as T
+
+  const upload = async (
+    body: Blob | ArrayBuffer | Uint8Array,
+    info: { name: string; mimeType: string },
+  ) => {
+    const query = new URLSearchParams({
+      threadId: options.threadId,
+      name: info.name,
+    })
+    const response = await doFetch(`${base}/media?${query}`, {
+      method: 'POST',
+      headers: { 'Content-Type': info.mimeType, ...headers() },
+      // fetch refuses a view on a SharedArrayBuffer. ponytail: a Uint8Array
+      // is copied once; skip the copy when `body.buffer` is an ArrayBuffer
+      // if big uploads from bytes (not a Blob or File) ever matter.
+      body: body instanceof Uint8Array ? body.slice() : body,
+    })
+    await checked('upload', response)
+    const stored: unknown = await response.json()
+    if (!isMediaRecord(stored))
+      throw new Error('Harness upload failed: the answer is not a media record')
+    return stored
+  }
+
+  const mediaUrl = async (id: string) => {
+    const body: unknown = await (await get('media-url', { id })).json()
+    if (!isSignedPath(body))
+      throw new Error('Harness media-url failed: the answer has no signed path')
+    return { url: `${base}/${body.path}`, expiresAt: body.expiresAt }
+  }
+
+  const loadMedia = async (id: string) =>
+    new Uint8Array(await (await get('media', { id })).arrayBuffer())
+
+  // `POST sessions`: rename, delete, or fork a session of this user.
+  const changeSession = async (change: SessionChange) =>
+    checked(
+      'sessions',
+      await doFetch(`${base}/sessions`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...headers() },
+        body: JSON.stringify(change),
+      }),
+    )
+
+  const sessionEntry = async (change: SessionChange) =>
+    // The handler answers a rename, an update, and a fork with the entry.
+    // The server schema checked its metadata.
+    (await (await changeSession(change)).json()) as SessionIndexEntry<
+      SessionMetadataOf<THarness>
+    >
+
+  async function* events(
+    eventOptions: {
+      from?: Cursor
+      signal?: AbortSignal
+      onConnection?: (state: 'open' | 'reconnecting') => void
+    } = {},
+  ) {
+    let cursor = eventOptions.from
+    const signal = eventOptions.signal
+    while (!signal?.aborted) {
+      try {
+        const query = new URLSearchParams({ threadId: options.threadId })
+        if (cursor) query.set('from', cursor)
+        const response = await doFetch(`${base}/events?${query}`, {
+          headers: headers(),
+          ...(signal ? { signal } : {}),
+        })
+        if (!response.ok || !response.body) {
+          throw new Error(`Harness events failed (${response.status})`)
+        }
+        eventOptions.onConnection?.('open')
+        for await (const frame of sseFrames(response.body, signal)) {
+          if (
+            typeof frame === 'object' &&
+            frame !== null &&
+            'type' in frame &&
+            frame.type === 'harness.event' &&
+            'cursor' in frame &&
+            typeof frame.cursor === 'string'
+          ) {
+            cursor = frame.cursor
+            // The handler sends `{ type, cursor, operationId, event }`.
+            const { type: _type, ...entry } = frame as SessionEvent & {
+              type: string
+            }
+            yield entry
+          }
+        }
+      } catch (error) {
+        if (signal?.aborted) return
+        if (error instanceof Error && /\((401|403|404)\)/.test(error.message))
+          throw error
+      }
+      if (signal?.aborted) return
+      eventOptions.onConnection?.('reconnecting')
+      await new Promise((resolve) =>
+        setTimeout(resolve, options.reconnectDelayMs ?? 1000),
+      )
+    }
+  }
+
+  async function* hostEvents({ signal }: { signal?: AbortSignal } = {}) {
+    try {
+      const response = await checked(
+        'host-events',
+        await doFetch(`${base}/host-events`, {
+          headers: headers(),
+          ...(signal ? { signal } : {}),
+        }),
+      )
+      if (!response.body)
+        throw new Error('Harness host-events failed: the answer has no body')
+      for await (const frame of sseFrames(response.body, signal)) {
+        // The handler sends `HostEvent` frames only.
+        yield frame as HostEvent
+      }
+    } catch (error) {
+      if (signal?.aborted) return
+      throw error
+    }
+  }
+
+  const agents = new Proxy({} as ClientAgentHandles<THarness>, {
+    get: (_target, name) =>
+      typeof name === 'string'
+        ? {
+            start: (input?: unknown, startOptions?: { detached?: boolean }) =>
+              send({
+                op: 'agent',
+                agent: name,
+                input,
+                ...(startOptions?.detached ? { detached: true } : {}),
+              }),
+          }
+        : undefined,
+  })
+
+  return {
+    prompt: (message, promptOptions) =>
+      send({
+        op: 'prompt',
+        message,
+        ...(promptOptions?.busy ? { busy: promptOptions.busy } : {}),
+        ...(promptOptions?.inputId ? { inputId: promptOptions.inputId } : {}),
+        ...(promptOptions?.ephemeral
+          ? { ephemeral: promptOptions.ephemeral }
+          : {}),
+      }),
+    steer: (message, steerOptions) =>
+      send({
+        op: 'steer',
+        message,
+        ...(steerOptions?.inputId ? { inputId: steerOptions.inputId } : {}),
+      }),
+    followUp: (message, followOptions) =>
+      send({
+        op: 'followUp',
+        message,
+        ...(followOptions?.inputId ? { inputId: followOptions.inputId } : {}),
+      }),
+    continue: (continueOptions) =>
+      send({
+        op: 'continue',
+        ...(continueOptions?.inputId
+          ? { inputId: continueOptions.inputId }
+          : {}),
+        ...(continueOptions?.ephemeral
+          ? { ephemeral: continueOptions.ephemeral }
+          : {}),
+      }),
+    resolve: (resume) => send({ op: 'resolve', resume }),
+    cancel: (operationId) =>
+      send({ op: 'cancel', ...(operationId ? { operationId } : {}) }),
+    cancelInput: (inputId) => send({ op: 'cancelInput', inputId }),
+    setDelivery: ({ inputId, delivery }) =>
+      send({ op: 'setDelivery', inputId, delivery }),
+    agents,
+    answer: ({ questionId, value }) =>
+      send({ op: 'answer', questionId, value }),
+    command: (name, input) => send({ op: 'command', name, input }),
+    setConfig: ({ key, value }) => send({ op: 'config', key, value }),
+    configure: (settings) => send({ op: 'configure', settings }),
+    reset: (note, resetOptions) =>
+      send({
+        op: 'reset',
+        ...(note !== undefined ? { note } : {}),
+        ...(resetOptions?.inputId ? { inputId: resetOptions.inputId } : {}),
+      }),
+    revert: (messageId) => send({ op: 'revert', messageId }),
+    unrevert: () => send({ op: 'unrevert' }),
+    sendToAgent: ({ operationId, message, mode, inputId }) =>
+      send({
+        op: 'agentMessage',
+        operationId,
+        message,
+        ...(mode ? { mode } : {}),
+        ...(inputId ? { inputId } : {}),
+      }),
+    events,
+    hostEvents,
+    snapshot: () => read('snapshot'),
+    transcript: () => read('transcript'),
+    agentTranscript: (subagentRunId) =>
+      read('agent-transcript', { subagentRunId }),
+    describe: () => read('describe'),
+    upload,
+    mediaUrl,
+    loadMedia,
+    listSessions: async ({
+      limit,
+      cursor,
+      parentThreadId,
+      search,
+      metadata = {},
+    } = {}) => {
+      const query = new URLSearchParams()
+      if (limit !== undefined) query.set('limit', String(limit))
+      if (cursor) query.set('cursor', cursor)
+      if (parentThreadId) query.set('parentThreadId', parentThreadId)
+      if (search) query.set('search', search)
+      for (const [key, value] of Object.entries(metadata))
+        query.set(`metadata.${key}`, value)
+      const response = await checked(
+        'sessions',
+        await doFetch(`${base}/sessions?${query}`, { headers: headers() }),
+      )
+      // The handler answers with one page of the session index.
+      return (await response.json()) as Omit<SessionIndexPage, 'entries'> & {
+        entries: Array<SessionIndexEntry<SessionMetadataOf<THarness>>>
+      }
+    },
+    renameSession: ({ threadId, title }) =>
+      sessionEntry({ op: 'rename', threadId, title }),
+    updateSession: (change) => sessionEntry({ ...change, op: 'update' }),
+    deleteSession: async (threadId) => {
+      await changeSession({ op: 'delete', threadId })
+    },
+    forkSession: ({ threadId, at }) =>
+      sessionEntry({ op: 'fork', threadId, ...at }),
+  }
+}
diff --git a/packages/ai-harness/src/connectors.ts b/packages/ai-harness/src/connectors.ts
new file mode 100644
index 0000000000..bd5639d999
--- /dev/null
+++ b/packages/ai-harness/src/connectors.ts
@@ -0,0 +1,112 @@
+import { defineCommand } from './commands'
+import { definePlugin } from './plugins'
+import {
+  deviceLogin,
+  isExpired,
+  loopbackLogin,
+  refreshCredential,
+} from './oauth'
+import type { AnyTool } from '@tanstack/ai'
+import type { OAuthConfig } from './oauth'
+
+export interface OAuthConnectorOptions {
+  /** A short id, for example `'github'`. Commands are `connect:<id>` and `disconnect:<id>`. */
+  id: string
+  label: string
+  oauth: OAuthConfig
+  /**
+   * How the user signs in. Required, because only you know where the harness
+   * runs:
+   *
+   * - `'device'`: show a code to enter on another device. It works on a
+   *   server, and needs `oauth.deviceUrl`.
+   * - `'loopback'`: open a browser on this machine and listen on
+   *   `127.0.0.1` for the redirect. Only for a harness that runs on the
+   *   user's own machine, such as a CLI.
+   */
+  login: 'loopback' | 'device'
+  /**
+   * The tools of this service. Call `token()` inside a tool: it returns a
+   * fresh access token, or fails with `auth_required` before sign-in. With
+   * `token({ wait: true })`, the turn waits for the sign-in and the tool
+   * runs again after it (see `CredentialsAccess.require`).
+   */
+  tools?: (
+    token: (options?: { wait?: boolean }) => Promise<string>,
+  ) => ReadonlyArray<AnyTool>
+  /** Test hook for the token endpoint. */
+  fetch?: typeof fetch
+}
+
+/**
+ * A plugin that signs the user in to an OAuth service and gives the model
+ * that service's tools. Adds `connect:<id>` and `disconnect:<id>` commands.
+ * Tokens stay in the credential store. The model never sees them.
+ *
+ * @example
+ * ```ts
+ * const github = oauthConnector({
+ *   id: 'github',
+ *   label: 'GitHub',
+ *   login: 'device',
+ *   oauth: { authorizationUrl, tokenUrl, deviceUrl, clientId, scopes: ['repo'] },
+ *   tools: (token) => [listIssues(token)],
+ * })
+ * ```
+ */
+export function oauthConnector(options: OAuthConnectorOptions) {
+  const { id, label, oauth } = options
+  return definePlugin({
+    name: `connector/${id}`,
+    setup: (ctx) => {
+      const token = async (tokenOptions?: {
+        wait?: boolean
+      }): Promise<string> => {
+        let credential = await ctx.credentials.require(id, tokenOptions)
+        if (credential.type === 'api_key') return credential.value
+        if (isExpired(credential) && credential.refreshToken) {
+          credential = await refreshCredential(oauth, credential, options.fetch)
+          await ctx.credentials.set({ id, credential })
+        }
+        if (credential.type === 'api_key') return credential.value
+        return credential.accessToken
+      }
+      return {
+        tools: options.tools?.(token) ?? [],
+        commands: {
+          [`connect:${id}`]: defineCommand({
+            description: `Sign in to ${label}`,
+            // The sign-in belongs to the user who runs the command.
+            run: async (_input, { credentials }) => {
+              const credential =
+                options.login === 'device'
+                  ? await deviceLogin(oauth, {
+                      onCode: ({ userCode, verificationUri }) =>
+                        ctx.session.authRequired({
+                          connector: id,
+                          url: verificationUri,
+                          userCode,
+                        }),
+                      ...(options.fetch ? { fetch: options.fetch } : {}),
+                    })
+                  : await loopbackLogin(oauth, {
+                      onUrl: (url) =>
+                        ctx.session.authRequired({ connector: id, url }),
+                      ...(options.fetch ? { fetch: options.fetch } : {}),
+                    })
+              await credentials.set({ id, credential })
+              return `Connected to ${label}.`
+            },
+          }),
+          [`disconnect:${id}`]: defineCommand({
+            description: `Sign out of ${label}`,
+            run: async (_input, { credentials }) => {
+              await credentials.delete(id)
+              return `Disconnected from ${label}.`
+            },
+          }),
+        },
+      }
+    },
+  })
+}
diff --git a/packages/ai-harness/src/define.ts b/packages/ai-harness/src/define.ts
index 798653b047..624ca436d7 100644
--- a/packages/ai-harness/src/define.ts
+++ b/packages/ai-harness/src/define.ts
@@ -267,7 +267,7 @@ export interface HarnessConfig<
     settings?: ReadonlyArray<keyof ThreadSettings>
     /**
      * The plugin config keys a client may set with a `config` input, for
-     * example `client.setConfig('model', 'fast')`. An input with any other
+     * example `client.setConfig({ key: 'model', value: 'fast' })`. An input with any other
      * key is refused with `not_exposed`. Server code that calls
      * `session.setConfig()` can set every key. Warning: `mode` of
      * `permissions()` lets a client turn approvals off with `bypass`. Keep
diff --git a/packages/ai-harness/src/host.ts b/packages/ai-harness/src/host.ts
index f0b1c201f7..cffbfdc675 100644
--- a/packages/ai-harness/src/host.ts
+++ b/packages/ai-harness/src/host.ts
@@ -496,6 +496,39 @@ function statusAfter(session: HarnessSession, event: StreamChunk) {
   }
 }
 
+/** How each host finds the open session of a chat turn. Not public API. */
+const turnFinders = new WeakMap<
+  object,
+  (harness: string, operationId: string) => Promise<HarnessSession | undefined>
+>()
+
+/**
+ * @internal The open session of `harness` in `host` that has the chat turn
+ * `operationId`, running or ended. A turn's events live in the host that runs
+ * it, so the handler joins a run through this.
+ */
+export function sessionOfTurn(
+  host: HarnessHost,
+  harness: AnyHarness,
+  operationId: string,
+): Promise<HarnessSession | undefined> {
+  return (
+    turnFinders.get(host)?.(harness.name, operationId) ??
+    Promise.resolve(undefined)
+  )
+}
+
+/** The log and run stores of each durable host. Not public API. */
+const durableStores = new WeakMap<object, { log: LogStore; runs?: RunStore }>()
+
+/**
+ * @internal The log and run stores of `host` when it is durable
+ * (`stores.log`), else `undefined`.
+ */
+export function durableStoresOf(host: HarnessHost) {
+  return durableStores.get(host)
+}
+
 /** Throw a clear error for a durable store set that cannot work. */
 function checkDurableStores(persistence: HarnessPersistence) {
   const { stores } = persistence
@@ -922,5 +955,17 @@ export function createHarnessHost<TLogState = undefined>(
       }
     },
   }
+  if (logStore) {
+    const { runs } = persistence.stores
+    durableStores.set(host, { log: logStore, ...(runs ? { runs } : {}) })
+  }
+  turnFinders.set(host, async (name, operationId) => {
+    for (const [key, opening] of sessions) {
+      if (!key.startsWith(`${name}\u0000`)) continue
+      const session = await opening.catch(() => undefined)
+      if (session?.operation(operationId)?.kind === 'chat') return session
+    }
+    return undefined
+  })
   return host
 }
diff --git a/packages/ai-harness/src/http.ts b/packages/ai-harness/src/http.ts
new file mode 100644
index 0000000000..9f71baf959
--- /dev/null
+++ b/packages/ai-harness/src/http.ts
@@ -0,0 +1,920 @@
+import {
+  EventType,
+  chatParamsFromRequestBody,
+  convertMessagesToModelMessages,
+  isContentPart,
+  modelMessagesToUIMessages,
+  readInterruptBinding,
+  resolveResumeRunId,
+  toServerSentEventsStream,
+} from '@tanstack/ai'
+import { parseRangeHeader, resolveBlobRange } from '@tanstack/ai-persistence'
+import { durableStoresOf, sessionOfTurn } from './host'
+import { MediaError } from './media'
+import { base64url } from './oauth'
+import {
+  HARNESS_PROTOCOL_VERSION,
+  applyInput,
+  capabilitiesOf,
+  describeForClient,
+  parseControlFrame,
+  parseHarnessInput,
+} from './protocol'
+import { isRecord } from './utils'
+import { SessionMetadataError } from './session-entry'
+import type {
+  ModelMessage,
+  RunStore,
+  UIMessage,
+  WebSocketLike,
+} from '@tanstack/ai'
+import type { SessionIndexEntry } from '@tanstack/ai-persistence'
+import type { AnyHarness } from './define'
+import type { HarnessHost, HostEvent } from './host'
+import type { HostFrame } from './protocol'
+import type { HarnessSession } from './session/index'
+import type { Principal, SessionEvent, UserInput } from './types'
+
+/**
+ * Decide who sends a request. Return `null` to refuse it with 401. Every
+ * endpoint calls it, except a signed media URL: the handler signs one only
+ * for a principal that `authorize` and `canAccess` let in.
+ */
+export type Authorize = (
+  request: Request,
+) => Principal | null | Promise<Principal | null>
+
+/** May this principal use this thread? */
+export type CanAccess = (
+  principal: Principal,
+  threadId: string,
+) => boolean | Promise<boolean>
+
+export interface HarnessHandlerOptions {
+  host: HarnessHost
+  harness: AnyHarness
+  authorize: Authorize
+  /**
+   * May this principal use this thread? Required: use it to keep users out
+   * of each other's threads. Pass `() => true` to let every principal use
+   * every thread.
+   */
+  canAccess: CanAccess
+  /**
+   * The secret that signs media URLs (HMAC SHA-256). Use the same value on
+   * every server behind one URL. Required on a durable host (`stores.log`),
+   * where another instance can serve the next request. Without a log store,
+   * the default is a random key per handler, so signed URLs stop working
+   * after a restart.
+   */
+  mediaSecret?: string
+}
+
+/** How long a signed media URL works. */
+const SIGNED_URL_TTL_MS = 60 * 60 * 1000
+
+const HMAC = { name: 'HMAC', hash: 'SHA-256' }
+
+// Every media answer: a browser must not guess another type, and a `text/*`
+// document must not run as a page of this origin.
+const MEDIA_HEADERS = {
+  'Accept-Ranges': 'bytes',
+  'X-Content-Type-Options': 'nosniff',
+  'Content-Security-Policy': "default-src 'none'; sandbox",
+}
+
+const encoder = new TextEncoder()
+
+const SSE_HEADERS = {
+  'Content-Type': 'text/event-stream',
+  'Cache-Control': 'no-cache',
+  Connection: 'keep-alive',
+}
+
+const json = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+
+/**
+ * An SSE response: one event per frame, with `data` as JSON and `id` when
+ * the frame has one. When the client leaves, `signal` aborts.
+ */
+function sseResponse(
+  frames: (
+    signal: AbortSignal,
+  ) => AsyncIterable<{ id?: string; data: unknown }>,
+) {
+  // Not `request.signal`: some servers abort it once the body is read.
+  const reader = new AbortController()
+  const body = new ReadableStream<Uint8Array>({
+    cancel: () => reader.abort(),
+    async start(controller) {
+      try {
+        for await (const { id, data } of frames(reader.signal)) {
+          const idLine = id === undefined ? '' : `id: ${id}\n`
+          controller.enqueue(
+            encoder.encode(`${idLine}data: ${JSON.stringify(data)}\n\n`),
+          )
+        }
+      } finally {
+        if (!reader.signal.aborted) controller.close()
+      }
+    },
+  })
+  return new Response(body, { headers: SSE_HEADERS })
+}
+
+/**
+ * Session events as an AG-UI SSE response. With `withIds`, each event has its
+ * cursor as `id`, so a client that loses the connection resumes with
+ * `Last-Event-ID`. When the client leaves, the read stops.
+ */
+function cursorResponse(
+  read: (signal: AbortSignal) => AsyncIterable<SessionEvent>,
+  withIds: boolean,
+) {
+  // Not `request.signal`: some servers abort it once the body is read.
+  const reader = new AbortController()
+  const cursors: Array<string> = []
+  async function* chunks() {
+    for await (const entry of read(reader.signal)) {
+      cursors.push(entry.cursor)
+      yield entry.event
+    }
+  }
+  return new Response(
+    toServerSentEventsStream(
+      chunks(),
+      reader,
+      withIds ? (_chunk, index) => cursors.at(index) : undefined,
+    ),
+    { headers: SSE_HEADERS },
+  )
+}
+
+/** A handler error as JSON: a `MediaError` keeps its status, the rest is 400. */
+const failed = (error: unknown) =>
+  error instanceof MediaError
+    ? json({ error: error.message }, error.status)
+    : json(
+        { error: error instanceof Error ? error.message : String(error) },
+        400,
+      )
+
+/**
+ * The content of the last user message of an AG-UI request, as TanStack
+ * content parts. Text stays a string. `undefined` when there is none.
+ */
+function lastUserInput(messages: Array<UIMessage | ModelMessage>) {
+  const message = messages.findLast((entry) => entry.role === 'user')
+  if (!message) return undefined
+  const [converted] = convertMessagesToModelMessages([message])
+  const content = converted?.content ?? ''
+  // The converter passes media parts through unchecked, so drop what is not
+  // a valid content part (for example an AG-UI `binary` part).
+  const input: UserInput = Array.isArray(content)
+    ? content.filter(isContentPart)
+    : content
+  return input
+}
+
+/** A `POST sessions` body, or `undefined` when it is not a valid one. */
+function parseSessionOp(body: unknown) {
+  if (!isRecord(body)) return undefined
+  const { op, threadId, title, before, through, pinned, metadata } = body
+  if (typeof threadId !== 'string') return undefined
+  switch (op) {
+    case 'rename':
+      return typeof title === 'string'
+        ? { op: 'rename' as const, threadId, title }
+        : undefined
+    case 'update':
+      if (title !== undefined && typeof title !== 'string') return undefined
+      if (pinned !== undefined && typeof pinned !== 'boolean') return undefined
+      if (
+        metadata !== undefined &&
+        (!isRecord(metadata) || Array.isArray(metadata))
+      )
+        return undefined
+      return {
+        op: 'update' as const,
+        threadId,
+        change: {
+          ...(title !== undefined ? { title } : {}),
+          ...(pinned !== undefined ? { pinned } : {}),
+          ...(metadata !== undefined ? { metadata } : {}),
+        },
+      }
+    case 'delete':
+      return { op: 'delete' as const, threadId }
+    case 'fork':
+      // Exactly one of `before` and `through`.
+      if (typeof before === 'string' && through === undefined)
+        return { op: 'fork' as const, threadId, at: { before } }
+      if (typeof through === 'string' && before === undefined)
+        return { op: 'fork' as const, threadId, at: { through } }
+      return undefined
+    default:
+      return undefined
+  }
+}
+
+/**
+ * The entry belongs to `principal`: the same id, and the same tenant when
+ * the principal has one. The same rule as the `principal` filter of the
+ * index `list`, so a user changes only the sessions the user can list.
+ */
+function isOwnedBy(entry: SessionIndexEntry, principal: Principal) {
+  const owner = entry.principal
+  if (!owner || owner.id !== principal.id) return false
+  return (
+    principal.tenantId === undefined || owner.tenantId === principal.tenantId
+  )
+}
+
+/** Base64url to bytes, or `undefined` for a value that is not base64url. */
+function fromBase64url(value: string) {
+  try {
+    const binary = atob(value.replace(/-/g, '+').replace(/_/g, '/'))
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The bytes of a media file as a response, with `Range` support: 206 for a
+ * slice, 416 for a range outside the file, and 404 for an id this thread
+ * does not have.
+ */
+async function mediaResponse(
+  request: Request,
+  session: HarnessSession,
+  id: string,
+) {
+  const record = await session.getMedia(id)
+  if (!record) return json({ error: 'not found' }, 404)
+  const range = parseRangeHeader(request.headers.get('Range'), record.size)
+  if (range === 'unsatisfiable') {
+    return new Response(null, {
+      status: 416,
+      headers: { ...MEDIA_HEADERS, 'Content-Range': `bytes */${record.size}` },
+    })
+  }
+  const bytes = await session.loadMedia(id, range)
+  const headers = {
+    ...MEDIA_HEADERS,
+    'Content-Type': record.mimeType,
+    'Content-Length': String(bytes.byteLength),
+  }
+  if (!range) return new Response(bytes, { headers })
+  const { offset, length } = resolveBlobRange(record.size, range)
+  return new Response(bytes, {
+    status: 206,
+    headers: {
+      ...headers,
+      'Content-Range': `bytes ${offset}-${offset + length - 1}/${record.size}`,
+    },
+  })
+}
+
+/**
+ * A fetch handler for a harness. Mount it on a route that ends with any of
+ * these paths:
+ *
+ * - `GET  .../capabilities`: the AG-UI capabilities document.
+ * - `POST .../run`: standard AG-UI. One request is one prompt (or one
+ *   `resume`), streamed as SSE. The turn runs as the request's `runId`, and a
+ *   retry with the same `runId` runs once. On a durable host, each event id
+ *   is its log cursor, and a retry with `Last-Event-ID` streams from there. The prompt keeps every content
+ *   part of the last user message, and its `forwardedProps` are the input's
+ *   `context`.
+ * - `GET  .../run?threadId=`: the transcript, the running turn, and the
+ *   waiting interrupts, as the `ChatHydrationResult` that a `ChatClient` with
+ *   `persistence` reads.
+ * - `GET  .../run?runId=` (or `X-Run-Id`): the chat turn with that run id, as
+ *   SSE from its start, so a reloaded `ChatClient` joins it. Each event id is
+ *   a cursor, so `Last-Event-ID` resumes it. On a durable host (`stores.log`
+ *   and `stores.runs`), any instance finds the turn in the shared log.
+ *   Without a log, 404 for a turn this host does not run.
+ * - `GET  .../events?threadId=&from=`: the session stream as SSE. Each event id
+ *   is a cursor, so `Last-Event-ID` resumes it.
+ * - `POST .../control`: `{ threadId, input }`. Returns the receipt.
+ * - `GET  .../snapshot?threadId=`: the session snapshot.
+ * - `GET  .../transcript?threadId=`: the saved messages of the thread.
+ * - `GET  .../agent-transcript?threadId=&subagentRunId=`: the saved messages
+ *   of a child agent run of the thread. Empty for an unknown id or a child
+ *   of another thread. 400 without `subagentRunId`.
+ * - `GET  .../describe?threadId=`: the commands, settings, and tools. Only
+ *   the commands in `expose.commands` and the config keys in `expose.config`.
+ * - `POST .../media?threadId=&name=`: store the raw body as a media file of
+ *   the thread, with `Content-Type` as its type. Returns the `MediaRecord`.
+ *   413 when it is over `media.maxBytes`, 415 for a type the harness does not
+ *   take.
+ * - `GET  .../media-url?threadId=&id=`: `{ path, expiresAt }`, a signed path
+ *   to the file, relative to the handler. It works for 1 hour.
+ * - `GET  .../media?threadId=&id=[&exp=&sig=]`: the bytes, with `Range`
+ *   support. A signed request needs no `authorize`, and a bad or expired
+ *   signature is 403.
+ * - `GET  .../sessions?limit=&cursor=&parentThreadId=`: one page of the
+ *   session index, newest first. Only the sessions of this principal that
+ *   `canAccess` lets in. Default: top-level sessions only.
+ * - `POST .../sessions`: change a session of this principal. The body is
+ *   `{ op: 'rename', threadId, title }`, `{ op: 'update', threadId, title?,
+ *   pinned?, metadata? }` (each field replaces the stored one, and the
+ *   harness `metadataSchema` checks `metadata`. Without a schema, a client
+ *   cannot write `metadata`: 403 `not_exposed`), `{ op: 'delete', threadId }`
+ *   (it removes the index entry only), or `{ op: 'fork', threadId, before }`
+ *   or `{ op: 'fork', threadId, through }` with a message id. Rename,
+ *   update, and fork answer with the entry, delete with 204. 400
+ *   (`invalid_metadata`, with `issues`) for metadata the schema refuses, 403
+ *   when `canAccess` refuses the thread, 404 for a thread this principal
+ *   does not own, and 409 (`other_harness`) for an update or a fork of a
+ *   thread that another harness runs.
+ * - `GET  .../host-events`: the `host.events()` of this principal as SSE:
+ *   status changes and session index changes. First the current status of
+ *   each open session. Only the threads that `canAccess` lets in and that
+ *   this principal owns in the session index, so it needs `stores.sessions`.
+ *
+ * Each chat input runs as the principal that `authorize` returned for its
+ * request, not as the one that opened the session first.
+ */
+export function createHarnessHandler(
+  options: HarnessHandlerOptions,
+): (request: Request) => Promise<Response> {
+  const { host, harness, authorize, canAccess } = options
+  const durable = durableStoresOf(host)
+  if (options.mediaSecret === undefined && durable) {
+    throw new Error(
+      'createHarnessHandler needs mediaSecret on a durable host (stores.log): another instance must verify the media URLs this one signs. Set the same secret on every instance.',
+    )
+  }
+
+  const openFor = async (principal: Principal, threadId: string) => {
+    if (!(await canAccess(principal, threadId))) return null
+    return host.open(harness, { threadId, principal })
+  }
+
+  // ponytail: without `mediaSecret` (only allowed without a log store), a
+  // random key per handler, so signed URLs stop working after a restart.
+  const secret =
+    options.mediaSecret === undefined
+      ? crypto.getRandomValues(new Uint8Array(32))
+      : encoder.encode(options.mediaSecret)
+  let key: Promise<CryptoKey> | undefined
+  const mediaKey = () =>
+    (key ??= crypto.subtle.importKey('raw', secret, HMAC, false, [
+      'sign',
+      'verify',
+    ]))
+  const signed = (threadId: string, id: string, exp: string) =>
+    encoder.encode(`${threadId}\n${id}\n${exp}`)
+  const sign = async (threadId: string, id: string, exp: string) => {
+    const signature = await crypto.subtle.sign(
+      'HMAC',
+      await mediaKey(),
+      signed(threadId, id, exp),
+    )
+    return base64url(new Uint8Array(signature))
+  }
+
+  /** Serve a signed media URL. The signature was made after `canAccess` passed. */
+  const serveSigned = async (request: Request, url: URL) => {
+    const param = (name: string) => url.searchParams.get(name) ?? ''
+    const threadId = param('threadId')
+    const id = param('id')
+    const exp = param('exp')
+    const signature = fromBase64url(param('sig'))
+    const isValid =
+      signature !== undefined &&
+      Number(exp) > Date.now() &&
+      // `verify` compares in constant time.
+      (await crypto.subtle.verify(
+        'HMAC',
+        await mediaKey(),
+        signature,
+        signed(threadId, id, exp),
+      ))
+    if (!isValid) return json({ error: 'forbidden' }, 403)
+    return mediaResponse(request, await host.open(harness, { threadId }), id)
+  }
+
+  /**
+   * Stream the chat turn `runId` from its start: the `joinRun` of a
+   * ChatClient after a reload. Each event has its cursor as `id`, so
+   * `Last-Event-ID` resumes after it. A turn that ended gives the events the
+   * feed still has.
+   */
+  const joinTurn = async (
+    request: Request,
+    principal: Principal,
+    runId: string,
+  ) => {
+    // `offset=-1` is the start. A reconnect sends the last cursor it saw.
+    const offset = new URL(request.url).searchParams.get('offset')
+    const resumeFrom =
+      request.headers.get('Last-Event-ID') ?? (offset === '-1' ? null : offset)
+    const session = await sessionOfTurn(host, harness, runId)
+    const turn = session?.operation(runId)
+    if (session && turn) {
+      if (!(await canAccess(principal, session.threadId))) {
+        return json({ error: 'forbidden' }, 403)
+      }
+      const startedCursor = session
+        .snapshot()
+        .activeOperations.find((item) => item.id === runId)?.startedCursor
+      const from = resumeFrom ?? startedCursor ?? '0'
+      return cursorResponse((signal) => turn.events({ from, signal }), true)
+    }
+    // Another instance runs the turn. A durable host finds its thread in the
+    // run store, and its events in the shared log. Not a child run or an
+    // agent run: only a chat turn of a thread.
+    const record = await durable?.runs?.get(runId)
+    const isChatTurn =
+      record != null &&
+      record.kind !== 'agent' &&
+      record.parentRunId === undefined
+    if (!record || !isChatTurn) return json({ error: 'unknown run' }, 404)
+    const { threadId } = record
+    if (!(await canAccess(principal, threadId))) {
+      return json({ error: 'forbidden' }, 403)
+    }
+    const entry = await host.sessions.get(threadId)
+    if (entry?.harness !== undefined && entry.harness !== harness.name) {
+      return json({ error: 'unknown run' }, 404)
+    }
+    const shared = await host.open(harness, { threadId, principal })
+    // ponytail: from the start of the log without a cursor. Store the
+    // started position on the run record if long threads make this slow.
+    return cursorResponse(
+      (signal) =>
+        followOperation(
+          shared.events({ from: resumeFrom ?? '0', signal }),
+          runId,
+        ),
+      true,
+    )
+  }
+
+  return async (request) => {
+    const url = new URL(request.url)
+    const route = url.pathname.split('/').at(-1)
+    const isSignedMedia =
+      request.method === 'GET' &&
+      route === 'media' &&
+      url.searchParams.has('sig')
+    // Before `authorize`: a signed URL is its own permission.
+    if (isSignedMedia) return serveSigned(request, url).catch(failed)
+    const principal = await authorize(request)
+    if (!principal) return json({ error: 'unauthorized' }, 401)
+
+    try {
+      if (request.method === 'GET' && route === 'capabilities') {
+        return json(capabilitiesOf(harness))
+      }
+
+      if (request.method === 'POST' && route === 'run') {
+        const params = await chatParamsFromRequestBody(await request.json())
+        const message = lastUserInput(params.messages)
+        const session = await openFor(principal, params.threadId)
+        if (!session) return json({ error: 'forbidden' }, 403)
+        // The turn runs as the request's run id, so an AG-UI client matches
+        // its events and interrupts. The run id is the input id too, so a
+        // retried request runs once. It runs as this request's principal.
+        const ids = { inputId: params.runId, runId: params.runId, principal }
+        const lastEventId = request.headers.get('Last-Event-ID')
+        if (params.resume && params.resume.length > 0) {
+          const receipt = await session.resolve(params.resume, ids)
+          if (receipt.status === 'rejected' || !receipt.operationId) {
+            return json({ error: receipt.reason ?? 'rejected' }, 409)
+          }
+          const { operationId } = receipt
+          return cursorResponse(
+            (signal) =>
+              followOperation(
+                session.events({
+                  ...(durable && lastEventId ? { from: lastEventId } : {}),
+                  signal,
+                }),
+                operationId,
+              ),
+            durable !== undefined,
+          )
+        }
+        if (message === undefined)
+          return json({ error: 'no user message' }, 400)
+        // AG-UI `forwardedProps` are the input's context.
+        const { forwardedProps } = params
+        const operation = session.prompt(message, {
+          ...ids,
+          ...(Object.keys(forwardedProps).length > 0
+            ? { context: forwardedProps }
+            : {}),
+        })
+        const receipt = await operation.receipt
+        if (receipt.status === 'rejected') {
+          return json({ error: receipt.reason ?? 'rejected' }, 409)
+        }
+        // A durable host sends each log cursor as the event id. A client cut
+        // off sends the same request with `Last-Event-ID`, maybe to another
+        // instance: the run id finds the same turn, and it streams from there.
+        // Without a log a cursor means nothing on another instance, so no id.
+        const from = (durable && lastEventId) || '0'
+        return cursorResponse(
+          (signal) => operation.events({ from, signal }),
+          durable !== undefined,
+        )
+      }
+
+      if (request.method === 'GET' && route === 'run') {
+        // The `joinRun` of a ChatClient after a reload names the run only.
+        const runId = resolveResumeRunId(request)
+        if (runId) return await joinTurn(request, principal, runId)
+        const threadId = url.searchParams.get('threadId')
+        if (!threadId) return json({ error: 'threadId is required' }, 400)
+        const session = await openFor(principal, threadId)
+        if (!session) return json({ error: 'forbidden' }, 403)
+        return json(await hydration(session, durable?.runs))
+      }
+
+      if (request.method === 'GET' && route === 'events') {
+        const threadId = url.searchParams.get('threadId')
+        if (!threadId) return json({ error: 'threadId is required' }, 400)
+        const session = await openFor(principal, threadId)
+        if (!session) return json({ error: 'forbidden' }, 403)
+        const from =
+          request.headers.get('Last-Event-ID') ??
+          url.searchParams.get('from') ??
+          undefined
+        return sseResponse(async function* (signal) {
+          const events = session.events({ ...(from ? { from } : {}), signal })
+          for await (const entry of events) {
+            const frame: HostFrame = { type: 'harness.event', ...entry }
+            yield { id: entry.cursor, data: frame }
+          }
+        })
+      }
+
+      if (request.method === 'GET' && route === 'host-events') {
+        // The same rule as `POST sessions`: `canAccess`, and the owner in
+        // the index. A deleted entry comes with the event.
+        const mayWatch = async (event: HostEvent) => {
+          if (!(await canAccess(principal, event.threadId))) return false
+          const entry =
+            event.type === 'status'
+              ? await host.sessions.get(event.threadId)
+              : event.entry
+          return entry !== undefined && isOwnedBy(entry, principal)
+        }
+        return sseResponse(async function* (signal) {
+          for await (const event of host.events({ signal })) {
+            if (await mayWatch(event)) yield { data: event }
+          }
+        })
+      }
+
+      if (request.method === 'POST' && route === 'control') {
+        const body: unknown = await request.json()
+        if (
+          typeof body !== 'object' ||
+          body === null ||
+          !('threadId' in body)
+        ) {
+          return json({ error: 'threadId is required' }, 400)
+        }
+        const threadId = body.threadId
+        if (typeof threadId !== 'string')
+          return json({ error: 'threadId is required' }, 400)
+        const input = parseHarnessInput(
+          'input' in body ? body.input : undefined,
+        )
+        const session = await openFor(principal, threadId)
+        if (!session) return json({ error: 'forbidden' }, 403)
+        return json(await applyInput(harness, session, input, principal))
+      }
+
+      if (
+        request.method === 'GET' &&
+        (route === 'transcript' || route === 'describe')
+      ) {
+        const threadId = url.searchParams.get('threadId')
+        if (!threadId) return json({ error: 'threadId is required' }, 400)
+        const session = await openFor(principal, threadId)
+        if (!session) return json({ error: 'forbidden' }, 403)
+        return json(
+          route === 'transcript'
+            ? await session.transcript()
+            : describeForClient(harness, session),
+        )
+      }
+
+      if (request.method === 'GET' && route === 'agent-transcript') {
+        const threadId = url.searchParams.get('threadId')
+        const subagentRunId = url.searchParams.get('subagentRunId')
+        if (!threadId) return json({ error: 'threadId is required' }, 400)
+        if (!subagentRunId)
+          return json({ error: 'subagentRunId is required' }, 400)
+        const session = await openFor(principal, threadId)
+        if (!session) return json({ error: 'forbidden' }, 403)
+        return json(await session.agentTranscript(subagentRunId))
+      }
+
+      if (request.method === 'GET' && route === 'snapshot') {
+        const threadId = url.searchParams.get('threadId')
+        if (!threadId) return json({ error: 'threadId is required' }, 400)
+        const session = await openFor(principal, threadId)
+        if (!session) return json({ error: 'forbidden' }, 403)
+        return json(session.snapshot())
+      }
+
+      if (request.method === 'GET' && route === 'sessions') {
+        const limit = url.searchParams.get('limit')
+        const cursor = url.searchParams.get('cursor')
+        const parentThreadId = url.searchParams.get('parentThreadId')
+        const isBadLimit =
+          limit !== null &&
+          !(Number.isInteger(Number(limit)) && Number(limit) > 0)
+        if (isBadLimit)
+          return json({ error: 'limit must be a positive integer' }, 400)
+        const search = url.searchParams.get('search')
+        // `metadata.<key>=<value>` asks for that exact metadata value.
+        const metadata = Object.fromEntries(
+          [...url.searchParams]
+            .filter(([key]) => key.startsWith('metadata.'))
+            .map(([key, value]) => [key.slice('metadata.'.length), value]),
+        )
+        // The store keeps only this principal's entries of this harness.
+        // `canAccess` can still refuse some of them.
+        const page = await host.sessions.list({
+          principal,
+          harness: harness.name,
+          metadata,
+          ...(limit ? { limit: Number(limit) } : {}),
+          ...(cursor ? { cursor } : {}),
+          ...(parentThreadId ? { parentThreadId } : {}),
+          ...(search ? { search } : {}),
+        })
+        const allowed = await Promise.all(
+          page.entries.map(async (entry) =>
+            canAccess(principal, entry.threadId),
+          ),
+        )
+        return json({
+          ...page,
+          entries: page.entries.filter((_entry, index) => allowed[index]),
+        })
+      }
+
+      if (request.method === 'POST' && route === 'sessions') {
+        const op = parseSessionOp(await request.json())
+        if (!op) return json({ error: 'not a valid sessions op' }, 400)
+        if (!(await canAccess(principal, op.threadId)))
+          return json({ error: 'forbidden' }, 403)
+        // The session of another user answers as a missing one, so its
+        // thread id tells the caller nothing.
+        const entry = await host.sessions.get(op.threadId)
+        if (!entry || !isOwnedBy(entry, principal))
+          return json({ error: 'not found' }, 404)
+        switch (op.op) {
+          case 'rename': {
+            const renamed = await host.sessions.rename({
+              threadId: op.threadId,
+              title: op.title,
+            })
+            return renamed ? json(renamed) : json({ error: 'not found' }, 404)
+          }
+          case 'update': {
+            // The host can run more harnesses than this handler serves.
+            if (entry.harness !== undefined && entry.harness !== harness.name)
+              return json({ error: 'other_harness' }, 409)
+            // The schema is the contract for what a client may write. Without
+            // one, metadata stays a server field.
+            if (op.change.metadata !== undefined && !harness.metadataSchema)
+              return json({ error: 'not_exposed' }, 403)
+            try {
+              const updated = await host.sessions.update({
+                harness,
+                threadId: op.threadId,
+                update: op.change,
+              })
+              return updated ? json(updated) : json({ error: 'not found' }, 404)
+            } catch (error) {
+              if (error instanceof SessionMetadataError)
+                return json(
+                  { error: 'invalid_metadata', issues: error.issues },
+                  400,
+                )
+              throw error
+            }
+          }
+          case 'delete':
+            await host.sessions.delete(op.threadId)
+            return new Response(null, { status: 204 })
+          case 'fork':
+            // The host can run more harnesses than this handler serves.
+            if (entry.harness !== undefined && entry.harness !== harness.name)
+              return json({ error: 'other_harness' }, 409)
+            return json(
+              await host.sessions.fork({
+                harness,
+                threadId: op.threadId,
+                at: op.at,
+              }),
+            )
+        }
+      }
+
+      if (request.method === 'POST' && route === 'media') {
+        const threadId = url.searchParams.get('threadId')
+        const name = url.searchParams.get('name')
+        if (!threadId || !name)
+          return json({ error: 'threadId and name are required' }, 400)
+        const session = await openFor(principal, threadId)
+        if (!session) return json({ error: 'forbidden' }, 403)
+        const record = await session.putMedia(
+          request.body ?? new Uint8Array(),
+          { mimeType: request.headers.get('Content-Type') ?? '', name },
+        )
+        return json(record)
+      }
+
+      if (
+        request.method === 'GET' &&
+        (route === 'media' || route === 'media-url')
+      ) {
+        const threadId = url.searchParams.get('threadId')
+        const id = url.searchParams.get('id')
+        if (!threadId || !id)
+          return json({ error: 'threadId and id are required' }, 400)
+        const session = await openFor(principal, threadId)
+        if (!session) return json({ error: 'forbidden' }, 403)
+        if (route === 'media') return await mediaResponse(request, session, id)
+        if (!(await session.getMedia(id)))
+          return json({ error: 'not found' }, 404)
+        const expiresAt = Date.now() + SIGNED_URL_TTL_MS
+        const exp = String(expiresAt)
+        const query = new URLSearchParams({
+          threadId,
+          id,
+          exp,
+          sig: await sign(threadId, id, exp),
+        })
+        return json({ path: `media?${query}`, expiresAt })
+      }
+    } catch (error) {
+      return failed(error)
+    }
+    return json({ error: 'not found' }, 404)
+  }
+}
+
+/**
+ * What a `ChatClient` with `persistence` reads when it loads a thread (a
+ * `ChatHydrationResult`): the transcript, the running chat turn (the client
+ * joins it with `GET run?runId=`), and the interrupts that the last turn
+ * waits for. On a durable host, `runs` finds a turn that another instance
+ * runs.
+ */
+async function hydration(session: HarnessSession, runs?: RunStore) {
+  const { pendingInterrupts, activeOperations } = session.snapshot()
+  const [first] = pendingInterrupts
+  const runId = first
+    ? readInterruptBinding(first)?.interruptedRunId
+    : undefined
+  const running = activeOperations.find(
+    (item) =>
+      item.kind === 'chat' &&
+      session.operation(item.id)?.status() === 'running',
+  )
+  const remote = running
+    ? undefined
+    : await runs?.findActiveRun(session.threadId)
+  const runningId =
+    running?.id ?? (remote?.kind !== 'agent' ? remote?.runId : undefined)
+  return {
+    messages: modelMessagesToUIMessages(await session.transcript()),
+    activeRun: runningId ? { runId: runningId } : null,
+    interrupts: runId ? { runId, pending: pendingInterrupts } : null,
+  }
+}
+
+/** Session events of one operation, until it finishes. */
+async function* followOperation(
+  events: AsyncIterable<SessionEvent>,
+  operationId: string,
+) {
+  for await (const entry of events) {
+    if (entry.operationId !== operationId) continue
+    yield entry
+    if (
+      entry.event.type === EventType.CUSTOM &&
+      entry.event.name === 'harness.operation.finished'
+    ) {
+      return
+    }
+  }
+}
+
+export interface HarnessSocketOptions {
+  host: HarnessHost
+  harness: AnyHarness
+  socket: WebSocketLike
+  /** The principal your upgrade handler authorized. */
+  principal: Principal
+  /** May this principal use this thread? Pass `() => true` to allow all. */
+  canAccess: CanAccess
+}
+
+/**
+ * Serve the session tier over one WebSocket. The first frame must be
+ * `harness.subscribe`. Authorize the upgrade request before you call this.
+ */
+export function handleHarnessSocket(options: HarnessSocketOptions): void {
+  const { host, harness, socket, principal, canAccess } = options
+  const reader = new AbortController()
+  // Set by the first subscribe, before its awaits, so a second subscribe is
+  // refused and an input sent right after the subscribe waits for the open.
+  let opened:
+    | Promise<Awaited<ReturnType<HarnessHost['open']>> | undefined>
+    | undefined
+  const send = (frame: HostFrame) => {
+    try {
+      socket.send(JSON.stringify(frame))
+    } catch {
+      reader.abort()
+    }
+  }
+
+  socket.addEventListener('close', () => reader.abort())
+  socket.addEventListener('error', () => reader.abort())
+  socket.addEventListener('message', (message) => {
+    void (async () => {
+      try {
+        const frame = parseControlFrame(String(message.data))
+        if (frame.type === 'harness.subscribe') {
+          if (opened) throw new Error('Already subscribed.')
+          const { threadId } = frame
+          opened = (async () =>
+            (await canAccess(principal, threadId))
+              ? host.open(harness, { threadId, principal })
+              : undefined)()
+          const session = await opened
+          if (!session) {
+            send({ type: 'harness.error', message: 'forbidden' })
+            socket.close(4403, 'forbidden')
+            return
+          }
+          send({
+            type: 'harness.hello',
+            v: HARNESS_PROTOCOL_VERSION,
+            threadId: frame.threadId,
+          })
+          const events = session.events({
+            ...(frame.from ? { from: frame.from } : {}),
+            signal: reader.signal,
+          })
+          void (async () => {
+            for await (const entry of events)
+              send({ type: 'harness.event', ...entry })
+          })()
+            .catch((error: unknown) =>
+              send({
+                type: 'harness.error',
+                message: error instanceof Error ? error.message : String(error),
+              }),
+            )
+            // The feed ended while the socket is open: close it, so the
+            // client subscribes again.
+            .finally(() => {
+              if (!reader.signal.aborted) socket.close(1011, 'feed ended')
+            })
+          return
+        }
+        const session = await opened
+        if (!session) throw new Error('Send harness.subscribe first.')
+        if (frame.type === 'harness.snapshot') {
+          send({ type: 'harness.snapshot', snapshot: session.snapshot() })
+          return
+        }
+        const receipt = await applyInput(
+          harness,
+          session,
+          frame.input,
+          principal,
+        )
+        send({
+          type: 'harness.receipt',
+          requestId: frame.requestId,
+          ...receipt,
+        })
+      } catch (error) {
+        send({
+          type: 'harness.error',
+          message: error instanceof Error ? error.message : String(error),
+        })
+      }
+    })()
+  })
+}
diff --git a/packages/ai-harness/src/index.ts b/packages/ai-harness/src/index.ts
index 89e16dcda4..ddba7ff167 100644
--- a/packages/ai-harness/src/index.ts
+++ b/packages/ai-harness/src/index.ts
@@ -167,8 +167,40 @@ export {
 export { MediaError } from './media'
 export type { MediaOptions } from './media'
 
+export {
+  HARNESS_PROTOCOL_VERSION,
+  applyInput,
+  capabilitiesOf,
+  parseControlFrame,
+  parseHarnessInput,
+} from './protocol'
+export type { ControlFrame, HostFrame } from './protocol'
+
+export { createHarnessHandler, handleHarnessSocket } from './http'
+export type {
+  Authorize,
+  CanAccess,
+  HarnessHandlerOptions,
+  HarnessSocketOptions,
+} from './http'
+
 export { harnessText } from './harness-text'
 export type { HarnessTextOptions, RemoteHarness } from './harness-text'
 
+export {
+  buildAuthorizationUrl,
+  createPkce,
+  deviceLogin,
+  exchangeCode,
+  isExpired,
+  loopbackLogin,
+  refreshCredential,
+  startLoopbackReceiver,
+} from './oauth'
+export type { OAuthConfig } from './oauth'
+
+export { oauthConnector } from './connectors'
+export type { OAuthConnectorOptions } from './connectors'
+
 export { harnessAgent } from './harness-agent'
 export { DEFAULT_SUBAGENT_LIMITS } from './session/index'
diff --git a/packages/ai-harness/src/oauth.ts b/packages/ai-harness/src/oauth.ts
new file mode 100644
index 0000000000..9e3a1b2492
--- /dev/null
+++ b/packages/ai-harness/src/oauth.ts
@@ -0,0 +1,366 @@
+import type { Credential } from '@tanstack/ai-persistence'
+
+/** An OAuth 2 app: where to send the user, and where to get tokens. */
+export interface OAuthConfig {
+  authorizationUrl: string
+  tokenUrl: string
+  /** The device authorization endpoint (RFC 8628), for logins without a browser here. */
+  deviceUrl?: string
+  clientId: string
+  /** Only for confidential clients. A CLI is a public client and has none. */
+  clientSecret?: string
+  scopes?: ReadonlyArray<string>
+}
+
+type Fetch = typeof fetch
+
+const encoder = new TextEncoder()
+
+/** Base64url (RFC 4648 section 5) without padding. */
+export function base64url(bytes: Uint8Array): string {
+  let binary = ''
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function randomString(bytes = 32): string {
+  return base64url(crypto.getRandomValues(new Uint8Array(bytes)))
+}
+
+/** A PKCE pair with the S256 method (RFC 7636). */
+export async function createPkce(): Promise<{
+  verifier: string
+  challenge: string
+}> {
+  const verifier = randomString(32)
+  const digest = await crypto.subtle.digest('SHA-256', encoder.encode(verifier))
+  return { verifier, challenge: base64url(new Uint8Array(digest)) }
+}
+
+/** The URL that starts a browser sign-in. */
+export function buildAuthorizationUrl(
+  config: OAuthConfig,
+  options: { redirectUri: string; state: string; challenge: string },
+): string {
+  const url = new URL(config.authorizationUrl)
+  url.searchParams.set('response_type', 'code')
+  url.searchParams.set('client_id', config.clientId)
+  url.searchParams.set('redirect_uri', options.redirectUri)
+  url.searchParams.set('state', options.state)
+  url.searchParams.set('code_challenge', options.challenge)
+  url.searchParams.set('code_challenge_method', 'S256')
+  if (config.scopes?.length)
+    url.searchParams.set('scope', config.scopes.join(' '))
+  return url.toString()
+}
+
+async function tokenRequest(
+  config: OAuthConfig,
+  body: Record<string, string>,
+  doFetch: Fetch,
+): Promise<Record<string, unknown>> {
+  const response = await doFetch(config.tokenUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json',
+    },
+    body: new URLSearchParams({
+      client_id: config.clientId,
+      ...(config.clientSecret ? { client_secret: config.clientSecret } : {}),
+      ...body,
+    }),
+  })
+  const parsed: unknown = await response.json().catch(() => ({}))
+  if (typeof parsed !== 'object' || parsed === null) {
+    throw new Error(`OAuth token request failed (${response.status}).`)
+  }
+  // An OAuth token endpoint answers with a flat JSON object.
+  return parsed as Record<string, unknown>
+}
+
+function credentialFrom(
+  response: Record<string, unknown>,
+  previous?: Credential,
+): Credential {
+  if (typeof response.access_token !== 'string') {
+    const reason =
+      typeof response.error === 'string' ? response.error : 'no access_token'
+    throw new Error(`OAuth token request failed: ${reason}`)
+  }
+  const refreshToken =
+    typeof response.refresh_token === 'string'
+      ? response.refresh_token
+      : previous?.type === 'oauth'
+        ? previous.refreshToken
+        : undefined
+  return {
+    type: 'oauth',
+    accessToken: response.access_token,
+    ...(refreshToken ? { refreshToken } : {}),
+    ...(typeof response.expires_in === 'number'
+      ? { expiresAt: Date.now() + response.expires_in * 1000 }
+      : {}),
+    ...(typeof response.scope === 'string'
+      ? { scopes: response.scope.split(/[ ,]/).filter(Boolean) }
+      : {}),
+  }
+}
+
+/** Trade an authorization code for tokens. */
+export async function exchangeCode(
+  config: OAuthConfig,
+  options: {
+    code: string
+    verifier: string
+    redirectUri: string
+    fetch?: Fetch
+  },
+): Promise<Credential> {
+  const response = await tokenRequest(
+    config,
+    {
+      grant_type: 'authorization_code',
+      code: options.code,
+      code_verifier: options.verifier,
+      redirect_uri: options.redirectUri,
+    },
+    options.fetch ?? fetch,
+  )
+  return credentialFrom(response)
+}
+
+/** True when an OAuth credential expires within `skewMs`. */
+export function isExpired(credential: Credential, skewMs = 60_000): boolean {
+  return (
+    credential.type === 'oauth' &&
+    credential.expiresAt !== undefined &&
+    credential.expiresAt - skewMs <= Date.now()
+  )
+}
+
+/** Get a new access token with the refresh token. */
+export async function refreshCredential(
+  config: OAuthConfig,
+  credential: Credential,
+  doFetch: Fetch = fetch,
+): Promise<Credential> {
+  if (credential.type !== 'oauth' || !credential.refreshToken) {
+    throw new Error('This credential has no refresh token.')
+  }
+  const response = await tokenRequest(
+    config,
+    { grant_type: 'refresh_token', refresh_token: credential.refreshToken },
+    doFetch,
+  )
+  return credentialFrom(response, credential)
+}
+
+const DONE_PAGE =
+  '<!doctype html><title>Signed in</title><p>You are signed in. You can close this tab.</p>'
+
+/**
+ * A one-time receiver for an OAuth redirect on `127.0.0.1` (RFC 8252). Use it
+ * when another library runs the OAuth flow and you only need the code back:
+ * register `redirectUri`, send the user to the authorization URL, then await
+ * `waitForCode(state)`. It answers one callback, then stops listening.
+ *
+ * `waitForCode` resolves with the code and the `iss` the server sent with it
+ * (RFC 9207). Pass `iss` on to the library: a server that sends it can refuse
+ * a code without it.
+ */
+export async function startLoopbackReceiver(
+  options: { timeoutMs?: number } = {},
+): Promise<{
+  redirectUri: string
+  waitForCode: (state: string) => Promise<{ code: string; iss?: string }>
+  close: () => void
+}> {
+  const { createServer } = await import('node:http')
+  const server = createServer()
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => resolve())
+  })
+  const address = server.address()
+  const port = typeof address === 'object' && address ? address.port : 0
+  const redirectUri = `http://127.0.0.1:${port}/callback`
+  const close = () => {
+    server.closeAllConnections()
+    server.close()
+  }
+  return {
+    redirectUri,
+    close,
+    waitForCode: (state) =>
+      new Promise((resolve, reject) => {
+        const timer = setTimeout(
+          () => {
+            close()
+            reject(new Error('Sign-in timed out.'))
+          },
+          options.timeoutMs ?? 10 * 60_000,
+        )
+        server.on('request', (req, res) => {
+          const url = new URL(req.url ?? '/', redirectUri)
+          if (url.pathname !== '/callback') {
+            res.writeHead(404).end()
+            return
+          }
+          clearTimeout(timer)
+          res.writeHead(200, { 'Content-Type': 'text/html' }).end(DONE_PAGE)
+          close()
+          const code = url.searchParams.get('code')
+          const iss = url.searchParams.get('iss')
+          if (url.searchParams.get('state') !== state) {
+            reject(new Error('Sign-in failed: the state does not match.'))
+          } else if (!code) {
+            reject(
+              new Error(
+                `Sign-in failed: ${url.searchParams.get('error') ?? 'no code'}`,
+              ),
+            )
+          } else resolve(iss ? { code, iss } : { code })
+        })
+      }),
+  }
+}
+
+/**
+ * Sign in through the browser with a loopback redirect (RFC 8252 + PKCE).
+ * Listens on `127.0.0.1` on a random port, for one callback only. Calls
+ * `onUrl` with the URL to open. Resolves with the tokens.
+ */
+export async function loopbackLogin(
+  config: OAuthConfig,
+  options: { onUrl: (url: string) => void; fetch?: Fetch; timeoutMs?: number },
+): Promise<Credential> {
+  const { createServer } = await import('node:http')
+  const { verifier, challenge } = await createPkce()
+  const state = randomString(16)
+  const server = createServer()
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => resolve())
+  })
+  const address = server.address()
+  const port = typeof address === 'object' && address ? address.port : 0
+  const redirectUri = `http://127.0.0.1:${port}/callback`
+
+  try {
+    const code = await new Promise<string>((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error('Sign-in timed out.')),
+        options.timeoutMs ?? 10 * 60_000,
+      )
+      server.on('request', (req, res) => {
+        const url = new URL(req.url ?? '/', redirectUri)
+        if (url.pathname !== '/callback') {
+          res.writeHead(404).end()
+          return
+        }
+        clearTimeout(timer)
+        const returnedState = url.searchParams.get('state')
+        const returnedCode = url.searchParams.get('code')
+        res.writeHead(200, { 'Content-Type': 'text/html' }).end(DONE_PAGE)
+        if (returnedState !== state)
+          reject(new Error('Sign-in failed: the state does not match.'))
+        else if (!returnedCode) {
+          reject(
+            new Error(
+              `Sign-in failed: ${url.searchParams.get('error') ?? 'no code'}`,
+            ),
+          )
+        } else resolve(returnedCode)
+      })
+      options.onUrl(
+        buildAuthorizationUrl(config, { redirectUri, state, challenge }),
+      )
+    })
+    return await exchangeCode(config, {
+      code,
+      verifier,
+      redirectUri,
+      ...(options.fetch ? { fetch: options.fetch } : {}),
+    })
+  } finally {
+    server.closeAllConnections()
+    server.close()
+  }
+}
+
+/**
+ * Sign in with a device code (RFC 8628), for SSH sessions, containers, and
+ * CI. Calls `onCode` with the code and the page to enter it on, then polls.
+ */
+export async function deviceLogin(
+  config: OAuthConfig,
+  options: {
+    onCode: (info: { userCode: string; verificationUri: string }) => void
+    fetch?: Fetch
+    /** Test hook. Default waits the interval the server asks for. */
+    sleep?: (ms: number) => Promise<void>
+  },
+): Promise<Credential> {
+  if (!config.deviceUrl)
+    throw new Error('This OAuth app has no device endpoint.')
+  const doFetch = options.fetch ?? fetch
+  const sleep =
+    options.sleep ??
+    ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)))
+  const started = await doFetch(config.deviceUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json',
+    },
+    body: new URLSearchParams({
+      client_id: config.clientId,
+      ...(config.scopes?.length ? { scope: config.scopes.join(' ') } : {}),
+    }),
+  })
+  const device: unknown = await started.json()
+  if (
+    typeof device !== 'object' ||
+    device === null ||
+    !('device_code' in device) ||
+    typeof device.device_code !== 'string' ||
+    !('user_code' in device) ||
+    typeof device.user_code !== 'string'
+  ) {
+    throw new Error('Device sign-in failed: the server sent no device code.')
+  }
+  const verificationUri =
+    'verification_uri' in device && typeof device.verification_uri === 'string'
+      ? device.verification_uri
+      : config.authorizationUrl
+  let interval =
+    'interval' in device && typeof device.interval === 'number'
+      ? device.interval * 1000
+      : 5000
+  const expiresAt =
+    Date.now() +
+    ('expires_in' in device && typeof device.expires_in === 'number'
+      ? device.expires_in * 1000
+      : 15 * 60_000)
+  options.onCode({ userCode: device.user_code, verificationUri })
+
+  while (Date.now() < expiresAt) {
+    await sleep(interval)
+    const response = await tokenRequest(
+      config,
+      {
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+        device_code: device.device_code,
+      },
+      doFetch,
+    )
+    if (response.error === 'authorization_pending') continue
+    if (response.error === 'slow_down') {
+      interval += 5000
+      continue
+    }
+    return credentialFrom(response)
+  }
+  throw new Error('Device sign-in expired.')
+}
diff --git a/packages/ai-harness/src/protocol.ts b/packages/ai-harness/src/protocol.ts
new file mode 100644
index 0000000000..5bdeb30d10
--- /dev/null
+++ b/packages/ai-harness/src/protocol.ts
@@ -0,0 +1,418 @@
+import { convertSchemaToJsonSchema } from '@tanstack/ai'
+import { isRecord } from './utils'
+import type { StreamChunk } from '@tanstack/ai'
+import type { AnyAgent } from './agents'
+import type { AnyHarness } from './define'
+import type { HarnessSession, SessionSnapshot } from './session/index'
+import type { Cursor, HarnessInput, Principal, Receipt } from './types'
+
+/** The session-tier protocol version. Sent in `subscribe` and `hello`. */
+export const HARNESS_PROTOCOL_VERSION = 1
+
+/** Client to host. */
+export type ControlFrame =
+  | { type: 'harness.subscribe'; threadId: string; from?: Cursor; v?: number }
+  | { type: 'harness.input'; requestId: string; input: HarnessInput }
+  | { type: 'harness.snapshot' }
+
+/** Host to client. */
+export type HostFrame =
+  | { type: 'harness.hello'; v: number; threadId: string }
+  | {
+      type: 'harness.receipt'
+      requestId: string
+      status: Receipt['status']
+      inputId?: string
+      operationId?: string
+      reason?: string
+    }
+  | {
+      type: 'harness.event'
+      cursor: Cursor
+      operationId: string
+      event: StreamChunk
+    }
+  | { type: 'harness.snapshot'; snapshot: SessionSnapshot }
+  | { type: 'harness.error'; message: string }
+
+const INPUT_OPS = new Set([
+  'prompt',
+  'steer',
+  'followUp',
+  'continue',
+  'resolve',
+  'agent',
+  'cancel',
+  'background',
+  'cancelInput',
+  'setDelivery',
+  'command',
+  'answer',
+  'config',
+  'configure',
+  'reset',
+  'revert',
+  'unrevert',
+  'agentMessage',
+])
+
+/** Check the shape of a client input. Throws with a short reason. */
+export function parseHarnessInput(value: unknown): HarnessInput {
+  if (
+    !isRecord(value) ||
+    typeof value.op !== 'string' ||
+    !INPUT_OPS.has(value.op)
+  ) {
+    throw new Error('Invalid input: expected { op } with a known op.')
+  }
+  const needsMessage =
+    value.op === 'prompt' ||
+    value.op === 'steer' ||
+    value.op === 'followUp' ||
+    value.op === 'agentMessage'
+  if (
+    needsMessage &&
+    typeof value.message !== 'string' &&
+    !Array.isArray(value.message)
+  ) {
+    throw new Error(`Invalid input: ${value.op} needs a message.`)
+  }
+  if (value.op === 'resolve' && !Array.isArray(value.resume)) {
+    throw new Error('Invalid input: resolve needs a resume array.')
+  }
+  if (value.op === 'agent' && typeof value.agent !== 'string') {
+    throw new Error('Invalid input: agent needs an agent name.')
+  }
+  if (value.op === 'agentMessage' && typeof value.operationId !== 'string') {
+    throw new Error('Invalid input: agentMessage needs an operationId.')
+  }
+  if (
+    value.op === 'agentMessage' &&
+    value.mode !== undefined &&
+    value.mode !== 'steer' &&
+    value.mode !== 'followUp'
+  ) {
+    throw new Error(
+      "Invalid input: the mode of agentMessage must be 'steer' or 'followUp'.",
+    )
+  }
+  if (value.op === 'command' && typeof value.name !== 'string') {
+    throw new Error('Invalid input: command needs a name.')
+  }
+  if (value.op === 'answer' && typeof value.questionId !== 'string') {
+    throw new Error('Invalid input: answer needs a questionId.')
+  }
+  if (value.op === 'config' && typeof value.key !== 'string') {
+    throw new Error('Invalid input: config needs a key.')
+  }
+  const namesInput = value.op === 'cancelInput' || value.op === 'setDelivery'
+  if (namesInput && typeof value.inputId !== 'string') {
+    throw new Error(`Invalid input: ${value.op} needs an inputId.`)
+  }
+  const isDelivery = value.delivery === 'steer' || value.delivery === 'queue'
+  if (value.op === 'setDelivery' && !isDelivery) {
+    throw new Error("Invalid input: setDelivery needs 'steer' or 'queue'.")
+  }
+  // The session checks each field, and answers a bad one with a receipt.
+  if (value.op === 'configure' && !isRecord(value.settings)) {
+    throw new Error('Invalid input: configure needs a settings object.')
+  }
+  if (
+    value.op === 'reset' &&
+    value.note !== undefined &&
+    typeof value.note !== 'string'
+  ) {
+    throw new Error('Invalid input: the note of reset must be a string.')
+  }
+  if (value.op === 'revert' && typeof value.messageId !== 'string') {
+    throw new Error('Invalid input: revert needs a messageId.')
+  }
+  if (
+    value.op === 'background' &&
+    value.toolCallId !== undefined &&
+    typeof value.toolCallId !== 'string'
+  ) {
+    throw new Error(
+      'Invalid input: the toolCallId of background must be a string.',
+    )
+  }
+  if (value.inputId !== undefined && typeof value.inputId !== 'string') {
+    throw new Error('Invalid input: inputId must be a string.')
+  }
+  // A client sends user messages only. An assistant or tool message from a
+  // client could fake an answer or a tool result in the model context.
+  const isUserMessage = (message: unknown) =>
+    isRecord(message) && message.role === 'user'
+  if (
+    (value.op === 'prompt' || value.op === 'continue') &&
+    value.ephemeral !== undefined &&
+    !(Array.isArray(value.ephemeral) && value.ephemeral.every(isUserMessage))
+  ) {
+    throw new Error(
+      'Invalid input: ephemeral must be an array of user messages.',
+    )
+  }
+  // Only the harness marks a wake follow-up. A client cannot.
+  if (value.op === 'followUp' && 'wake' in value) {
+    const { wake: _wake, ...input } = value
+    return input as HarnessInput
+  }
+  // The checks above cover every field the session reads.
+  return value as HarnessInput
+}
+
+/** Parse one text frame from a client. Throws with a short reason. */
+export function parseControlFrame(data: string): ControlFrame {
+  const value: unknown = JSON.parse(data)
+  if (!isRecord(value)) throw new Error('Invalid frame.')
+  if (
+    value.type === 'harness.subscribe' &&
+    typeof value.threadId === 'string'
+  ) {
+    return {
+      type: 'harness.subscribe',
+      threadId: value.threadId,
+      ...(typeof value.from === 'string' ? { from: value.from } : {}),
+    }
+  }
+  if (value.type === 'harness.input' && typeof value.requestId === 'string') {
+    return {
+      type: 'harness.input',
+      requestId: value.requestId,
+      input: parseHarnessInput(value.input),
+    }
+  }
+  if (value.type === 'harness.snapshot') return { type: 'harness.snapshot' }
+  throw new Error('Invalid frame: unknown type.')
+}
+
+/**
+ * Apply a client input to a session. A client can run, or send messages to,
+ * only the agents in `expose.agents`. It can run only the commands in
+ * `expose.commands`, and change only the settings in `expose.settings` and the
+ * config keys in `expose.config`. Resolves to the receipt. `principal` is who
+ * sent the input, from your `authorize`, never from the input itself. A chat
+ * input runs with its credentials.
+ */
+export async function applyInput(
+  harness: AnyHarness,
+  session: HarnessSession,
+  input: HarnessInput,
+  principal?: Principal,
+): Promise<Receipt> {
+  const id = {
+    ...(input.inputId === undefined ? {} : { inputId: input.inputId }),
+    ...(principal ? { principal } : {}),
+  }
+  const sent = {
+    ...id,
+    ...('context' in input && input.context !== undefined
+      ? { context: input.context }
+      : {}),
+  }
+  const notExposed: Receipt = {
+    inputId: input.inputId ?? '',
+    status: 'rejected',
+    reason: 'not_exposed',
+  }
+  switch (input.op) {
+    case 'prompt': {
+      const operation = session.prompt(input.message, {
+        ...(input.busy ? { busy: input.busy } : {}),
+        ...(input.ephemeral ? { ephemeral: input.ephemeral } : {}),
+        ...sent,
+      })
+      // Nobody may await a turn a client started. Its receipt is the answer.
+      operation.then(
+        () => {},
+        () => {},
+      )
+      return operation.receipt
+    }
+    case 'continue': {
+      const operation = session.continue({
+        ...(input.ephemeral ? { ephemeral: input.ephemeral } : {}),
+        ...sent,
+      })
+      operation.then(
+        () => {},
+        () => {},
+      )
+      return operation.receipt
+    }
+    case 'steer':
+      return session.steer(input.message, sent)
+    case 'followUp':
+      return session.followUp(input.message, sent)
+    case 'resolve':
+      return session.resolve(input.resume, id)
+    case 'cancel':
+      return session.cancel(input.operationId)
+    // It runs no new code, so it needs no `expose` entry, like `cancel`.
+    case 'background':
+      return session.background(input.toolCallId)
+    case 'cancelInput':
+      return session.cancelInput(input.inputId)
+    case 'setDelivery':
+      return session.setDelivery({
+        inputId: input.inputId,
+        delivery: input.delivery,
+      })
+    case 'command': {
+      // A command can change the session, for example `/mode bypass`.
+      if (!(harness.expose?.commands ?? []).includes(input.name)) {
+        return notExposed
+      }
+      const operation = session.command(
+        input.name,
+        input.input,
+        principal ? { principal } : undefined,
+      )
+      operation.then(
+        () => {},
+        () => {},
+      )
+      return {
+        inputId: operation.id,
+        status: 'accepted',
+        operationId: operation.id,
+      }
+    }
+    case 'answer':
+      return session.answer({
+        questionId: input.questionId,
+        value: input.value,
+      })
+    case 'config':
+      if (!(harness.expose?.config ?? []).includes(input.key)) {
+        return notExposed
+      }
+      return session.setConfig({ key: input.key, value: input.value })
+    case 'configure': {
+      // A client changes only the settings the harness exposes.
+      const exposed: ReadonlyArray<string> = harness.expose?.settings ?? []
+      const isExposed = Object.keys(input.settings).every((key) =>
+        exposed.includes(key),
+      )
+      if (!isExposed) return notExposed
+      return session.configure(input.settings, id)
+    }
+    case 'reset':
+      return session.reset(input.note, id)
+    // A revert puts files back, as `/undo` does.
+    case 'revert':
+    case 'unrevert':
+      if (!(harness.expose?.commands ?? []).includes('undo')) return notExposed
+      return input.op === 'revert'
+        ? session.revert(input.messageId)
+        : session.unrevert()
+    case 'agent': {
+      const exposed = (harness.expose?.agents ?? []).includes(input.agent)
+      if (!exposed) {
+        return { inputId: '', status: 'rejected', reason: 'not_exposed' }
+      }
+      const handle = session.agent(input.agent)
+      if (!handle) {
+        return { inputId: '', status: 'rejected', reason: 'unknown_agent' }
+      }
+      const operation = handle.start(input.input, {
+        wake: input.detached === true,
+      })
+      return {
+        inputId: operation.id,
+        status: 'accepted',
+        operationId: operation.id,
+      }
+    }
+    case 'agentMessage': {
+      const run = session.agentRun(input.operationId)
+      if (!run) {
+        return {
+          inputId: input.inputId ?? '',
+          status: 'rejected',
+          reason: 'not_running',
+        }
+      }
+      // Only a run of an exposed agent takes messages from a client.
+      const exposed: ReadonlyArray<string> = harness.expose?.agents ?? []
+      if (!exposed.includes(run.agent ?? '')) {
+        return {
+          inputId: input.inputId ?? '',
+          status: 'rejected',
+          reason: 'not_exposed',
+        }
+      }
+      return session.sendToAgent({
+        operationId: input.operationId,
+        message: input.message,
+        ...id,
+        ...(input.mode ? { mode: input.mode } : {}),
+      })
+    }
+  }
+}
+
+/**
+ * What `describe` sends a client: only the commands in `expose.commands` and
+ * the config keys in `expose.config`, so a UI shows only what `applyInput`
+ * lets through. Server code reads the full `session.describe()`.
+ */
+export function describeForClient(
+  harness: AnyHarness,
+  session: HarnessSession,
+) {
+  const description = session.describe()
+  const commands: ReadonlyArray<string> = harness.expose?.commands ?? []
+  const config: ReadonlyArray<string> = harness.expose?.config ?? []
+  return {
+    ...description,
+    commands: description.commands.filter(({ name }) =>
+      commands.includes(name),
+    ),
+    config: description.config.filter(({ key }) => config.includes(key)),
+  }
+}
+
+/** The AG-UI capabilities document of a harness. */
+export function capabilitiesOf(harness: AnyHarness) {
+  const exposed = new Set<string>(harness.expose?.agents ?? [])
+  const subagents: ReadonlyArray<AnyAgent> = harness.subagents?.agents ?? []
+  const agents: ReadonlyArray<AnyAgent> = [
+    ...(harness.agents ?? []),
+    ...subagents,
+  ]
+  return {
+    identity: { name: harness.name, type: 'tanstack-ai-harness' },
+    transport: { streaming: true, websocket: true },
+    tools: {
+      supported: true,
+      items: (harness.tools ?? []).map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+      })),
+    },
+    multiAgent: {
+      supported: agents.length > 0,
+      subagents: subagents.map((agent) => ({
+        name: agent.name,
+        description: agent.description,
+      })),
+    },
+    humanInTheLoop: { supported: true, interrupts: true },
+    custom: {
+      tanstack: {
+        protocol: HARNESS_PROTOCOL_VERSION,
+        agents: agents
+          .filter((agent) => exposed.has(agent.name))
+          .map((agent) => ({
+            name: agent.name,
+            description: agent.description,
+            ...(agent.produces ? { produces: agent.produces } : {}),
+            ...(agent.inputSchema
+              ? { inputSchema: convertSchemaToJsonSchema(agent.inputSchema) }
+              : {}),
+          })),
+      },
+    },
+  }
+}
diff --git a/packages/ai-harness/src/view/index.ts b/packages/ai-harness/src/view/index.ts
new file mode 100644
index 0000000000..91e9c03417
--- /dev/null
+++ b/packages/ai-harness/src/view/index.ts
@@ -0,0 +1,1026 @@
+// Browser-safe: runtime imports only from @tanstack/ai, @tanstack/store,
+// ../types, ../media-ref, and ./reduce. Everything else is a type.
+import {
+  EventType,
+  readUnopenedInterruptBinding,
+  wireSubagentInfo,
+} from '@tanstack/ai'
+import { createStore } from '@tanstack/store'
+import { mediaPart } from '../media-ref'
+import { HARNESS_EVENTS } from '../types'
+import {
+  agentPartsFrom,
+  applyDescription,
+  applyEvent,
+  applySnapshot,
+  emptyAgentsIn,
+  emptyState,
+  keep,
+  messagesFromTranscript,
+  notAccepted,
+  subagentOf,
+  transcriptIds,
+  withAgentParts,
+  withNotice,
+  withUserMessage,
+} from './reduce'
+import type {
+  ContentPart,
+  ModelMessage,
+  RunAgentResumeItem,
+} from '@tanstack/ai'
+import type { ReadonlyStore } from '@tanstack/store'
+import type { PluginEvent } from '../extensions'
+import type { SessionDescription, SessionSnapshot } from '../session/index'
+import type {
+  Cursor,
+  MediaRecord,
+  Receipt,
+  SessionEvent,
+  ThreadSettingsChange,
+  UserInput,
+  WaitingInput,
+} from '../types'
+import type { ItemFactory } from './reduce'
+import type {
+  AgentPart,
+  Approval,
+  ApproveOptions,
+  ClientToolCall,
+  MediaPart,
+  SessionViewState,
+  SignIn,
+  ViewInterrupt,
+  ViewMessage,
+  ViewPart,
+  ViewQuestion,
+} from './types'
+
+export {
+  MEDIA_URL_PREFIX,
+  kindOf,
+  mediaIdOf,
+  mediaOfMessage,
+  mediaPart,
+} from '../media-ref'
+export type { MediaKind, MediaRecord, WaitingInput } from '../types'
+export type {
+  AgentPart,
+  Approval,
+  ApproveOptions,
+  ClientToolCall,
+  MediaPart,
+  NoticeKind,
+  SessionViewState,
+  SignIn,
+  ToolCallPart,
+  ToolCallStatus,
+  ViewAgent,
+  ViewCommand,
+  ViewConfigEntry,
+  ViewInterrupt,
+  ViewMessage,
+  ViewPart,
+  ViewQuestion,
+} from './types'
+
+/** Lead events of a model call that come after its reasoning. */
+const CALL_EVENTS: ReadonlySet<string> = new Set([
+  EventType.TEXT_MESSAGE_START,
+  EventType.TEXT_MESSAGE_CONTENT,
+  EventType.TOOL_CALL_START,
+  EventType.TOOL_CALL_ARGS,
+  EventType.TOOL_CALL_END,
+  EventType.TOOL_CALL_RESULT,
+])
+
+/** How a saved child ended, from the card on its messages. */
+function endOf(messages: ReadonlyArray<ModelMessage>) {
+  const status = messages.map(wireSubagentInfo).find(Boolean)?.status
+  if (status === 'finished') return 'done'
+  return status === 'error' ? 'failed' : undefined
+}
+
+/** A retry that runs the model call again, with none of its output. */
+function isRetry({ event }: SessionEvent) {
+  return (
+    event.type === EventType.CUSTOM &&
+    event.name === HARNESS_EVENTS.turnRetry &&
+    !(
+      typeof event.value === 'object' &&
+      event.value !== null &&
+      'continued' in event.value &&
+      event.value.continued === true
+    )
+  )
+}
+
+/** The end of a lead run or of an operation. */
+function isEnd({ event }: SessionEvent) {
+  if (event.type === EventType.CUSTOM)
+    return event.name === HARNESS_EVENTS.operationFinished
+  const isRunEnd =
+    event.type === EventType.RUN_FINISHED || event.type === EventType.RUN_ERROR
+  return isRunEnd && !('subagentRunId' in event && event.subagentRunId)
+}
+
+/** Get a new media URL this long before the old one expires. */
+const URL_REFRESH_EARLY = 60_000
+
+/** A local `HarnessSession` and a remote `HarnessClient` both fit this. */
+export interface SessionViewSource {
+  prompt: (message: UserInput) => unknown
+  steer: (message: UserInput) => Promise<Receipt>
+  resolve: (resume: Array<RunAgentResumeItem>) => Promise<Receipt>
+  cancel: (operationId?: string) => Promise<Receipt>
+  // Both sources have these. Without one, its view action shows an error.
+  followUp?: (message: UserInput) => Promise<Receipt>
+  continue?: () => unknown
+  cancelInput?: (inputId: string) => Promise<Receipt>
+  setDelivery?: (change: {
+    inputId: string
+    delivery: WaitingInput['delivery']
+  }) => Promise<Receipt>
+  configure?: (settings: ThreadSettingsChange) => Promise<Receipt>
+  reset?: (note?: string) => Promise<Receipt>
+  revert?: (messageId: string) => Promise<Receipt>
+  unrevert?: () => Promise<Receipt>
+  answer: (answer: { questionId: string; value: unknown }) => Promise<Receipt>
+  command: (name: string, input?: unknown) => unknown
+  setConfig: (change: { key: string; value: unknown }) => Promise<Receipt>
+  /** Send a message to an agent run. Without it, an agent's `send` rejects. */
+  sendToAgent?: (options: {
+    operationId: string
+    message: UserInput
+    mode?: 'steer' | 'followUp'
+  }) => Promise<Receipt>
+  events: (options: {
+    from?: Cursor
+    signal?: AbortSignal
+    onConnection?: (state: 'open' | 'reconnecting') => void
+  }) => AsyncIterable<SessionEvent>
+  snapshot: () => SessionSnapshot | Promise<SessionSnapshot>
+  transcript: () => Promise<Array<ModelMessage>>
+  describe: () => SessionDescription | Promise<SessionDescription>
+  /** A URL for a media file. Without it, media parts have no `url`. */
+  mediaUrl?: (id: string) => Promise<{ url?: string; expiresAt?: number }>
+  /** The bytes of a media file. Without it, `load()` rejects. */
+  loadMedia?: (id: string) => Promise<Uint8Array>
+  /** Store a file: `upload` on a client, `putMedia` on a session. */
+  upload?: (body: MediaBody, info: MediaInfo) => Promise<MediaRecord>
+  putMedia?: (body: MediaBody, info: MediaInfo) => Promise<MediaRecord>
+  /** The saved messages of a child agent run. Without it, a reload shows no child parts. */
+  agentTranscript?: (subagentRunId: string) => Promise<Array<ModelMessage>>
+}
+
+/** The bytes of a file to store. */
+type MediaBody = ArrayBuffer | Uint8Array
+type MediaInfo = { name: string; mimeType: string }
+
+/**
+ * What `view.on(name, handler)` sends.
+ *
+ * @experimental The event names and values can change in a minor release.
+ */
+export interface SessionViewEvents {
+  approval: Approval
+  clientTool: ClientToolCall
+  interrupt: ViewInterrupt
+  question: ViewQuestion
+  signIn: SignIn
+  toolCall: { id: string; name: string }
+  agent: { id: string; name: string; status: 'running' | 'done' | 'failed' }
+  error: string
+  /** A chat turn ended. A turn that stops for an interrupt does not end. */
+  turnEnd: { operationId: string }
+}
+
+/** A name from `SessionViewEvents`, or a plugin event from `createPluginEvent`. */
+type ViewEventKey = keyof SessionViewEvents | PluginEvent<unknown>
+
+/** The value that `view.on(key, handler)` gives to `handler`. */
+type ViewEventValue<K> = K extends keyof SessionViewEvents
+  ? SessionViewEvents[K]
+  : K extends PluginEvent<infer T>
+    ? T
+    : never
+
+export interface SessionView {
+  /** The live state. Read it with `get()`, `subscribe()`, or `useSelector()`. */
+  store: ReadonlyStore<SessionViewState>
+  /** Resolves when history, the first snapshot, and the description are in. */
+  ready: Promise<void>
+  /**
+   * A `/command`, a prompt, or a steer while a turn runs. `attachments` are
+   * stored media files (from `upload`) that go with the text.
+   * A `/command` ignores them. Empty text with no attachments does nothing.
+   */
+  send: (
+    text: string,
+    attachments?: ReadonlyArray<MediaRecord>,
+  ) => Promise<void>
+  /** A message that runs as its own turn after the current work. */
+  followUp: (
+    text: string,
+    attachments?: ReadonlyArray<MediaRecord>,
+  ) => Promise<void>
+  /** Start a turn from the saved messages, with no new message. */
+  continue: () => Promise<void>
+  /** Store a file. Send its record with `send(text, [record])`. */
+  upload: (body: MediaBody, info: MediaInfo) => Promise<MediaRecord>
+  command: (name: string, input?: unknown) => Promise<void>
+  setConfig: (change: { key: string; value: unknown }) => Promise<void>
+  /** Change the stored settings of the thread, for example the model. */
+  configure: (settings: ThreadSettingsChange) => Promise<void>
+  /** Stop the running turn, or the operation `operationId`. */
+  cancel: (operationId?: string) => Promise<void>
+  /** Drop an input from `waitingInputs` before it runs. */
+  cancelInput: (inputId: string) => Promise<void>
+  /** Move a waiting input: `'steer'` joins the running turn, `'queue'` waits for its own turn. */
+  setDelivery: (change: {
+    inputId: string
+    delivery: WaitingInput['delivery']
+  }) => Promise<void>
+  /** Start a fresh model context. The model sees `note` first. */
+  reset: (note?: string) => Promise<void>
+  /** Go back to the message `messageId`. `unrevert` undoes it. */
+  revert: (messageId: string) => Promise<void>
+  unrevert: () => Promise<void>
+  approve: (id: string, options?: ApproveOptions) => void
+  reject: (id: string, payload?: unknown) => void
+  approveAll: () => void
+  rejectAll: () => void
+  /** Add a line of your own to the messages. */
+  notice: (text: string) => void
+  /**
+   * Listen for a view event (`'approval'`, `'turnEnd'`, ...) or a plugin event.
+   * Returns a function that stops listening.
+   */
+  on: <K extends ViewEventKey>(
+    key: K,
+    handler: (value: ViewEventValue<K>) => void,
+  ) => () => void
+  /** Stop reading events and getting new media URLs. Later actions throw. */
+  dispose: () => void
+}
+
+/** What a line and its attachments send: plain text when there are none. */
+function userInput(line: string, attachments: ReadonlyArray<MediaRecord>) {
+  if (attachments.length === 0) return line
+  const files = attachments.map(mediaPart)
+  const input: Array<ContentPart> =
+    line === '' ? files : [{ type: 'text', content: line }, ...files]
+  return input
+}
+
+/** Events after which the snapshot can differ. */
+function changesSnapshot(entry: SessionEvent) {
+  const { event } = entry
+  if (
+    event.type === EventType.RUN_STARTED ||
+    event.type === EventType.RUN_FINISHED ||
+    event.type === EventType.RUN_ERROR
+  ) {
+    return !('subagentRunId' in event && event.subagentRunId)
+  }
+  return (
+    event.type === EventType.CUSTOM &&
+    /^harness\.(operation|input|question|config|usage)/.test(event.name)
+  )
+}
+
+/**
+ * A receipt that `applyInput` refused before the session saw the input. The
+ * session reports its own refusals with a `harness.input.rejected` event, so
+ * the view shows only this one from the receipt.
+ */
+function isNotExposed(value: unknown) {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'reason' in value &&
+    value.reason === 'not_exposed'
+  )
+}
+
+function isOperation(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'status' in value &&
+    typeof value.status === 'function' &&
+    'then' in value
+  )
+}
+
+/** Run `task` now, or once more after the running one ends. */
+function coalesce(task: () => Promise<void>) {
+  let running = false
+  let again = false
+  const run = async () => {
+    running = true
+    do {
+      again = false
+      await task()
+    } while (again)
+    running = false
+  }
+  return () => {
+    if (running) again = true
+    else void run()
+  }
+}
+
+/**
+ * A live view of a harness session for any UI. It reads the events, keeps one
+ * state in a TanStack Store, and gives actions and typed events.
+ *
+ * @param source A local `HarnessSession` (from `host.open`) or a remote
+ * `HarnessClient` (from `createHarnessClient`).
+ *
+ * @example
+ * ```ts
+ * const view = createSessionView(session)
+ * view.store.subscribe((state) => draw(state))
+ * view.on('approval', (approval) => approval.approve())
+ * await view.send('fix the failing test')
+ * ```
+ *
+ * @experimental The view API and its state can change in a minor release.
+ */
+export function createSessionView(source: SessionViewSource) {
+  const internal = createStore(emptyState())
+  const store = createStore(() => internal.state)
+  const reader = new AbortController()
+  const handlers = new Map<string, Set<(value: unknown) => void>>()
+  /** The answer to each open approval and client tool, by interrupt id. */
+  const decisions = new Map<string, RunAgentResumeItem>()
+  const chatTurns = new Set<string>()
+  const agentNames = new Map<string, string>()
+  const mediaParts = new Map<string, MediaPart>()
+  const urlRefreshes = new Map<string, ReturnType<typeof setTimeout>>()
+  /** The media ids the last commit shows. */
+  let shownMedia = new Set<string>()
+  /** The agent parts of a reload that loaded, or load now. */
+  const loadedAgents = new Set<string>()
+  /** The ids the first transcript has. See `replayed`. */
+  let saved = new Set<string>()
+  /** The replay of the operations that ran at start ends at this cursor. */
+  let replayEnd = -1
+  let replayOps = new Set<string>()
+  /** Replayed lead reasoning that waits for its model call. See `replayed`. */
+  let held: Array<SessionEvent> = []
+  let resolving = false
+  let disposed = false
+
+  const get = () => internal.state
+  const commit = (next: SessionViewState) => {
+    if (disposed) return
+    shownMedia = new Set()
+    const shown = withMediaActions(next)
+    // A media file that no message shows now (after a revert) needs no URL.
+    for (const id of mediaParts.keys()) {
+      if (shownMedia.has(id)) continue
+      clearTimeout(urlRefreshes.get(id))
+      urlRefreshes.delete(id)
+      mediaParts.delete(id)
+    }
+    if (shown !== internal.state) internal.setState(() => shown)
+  }
+  const emit = (key: string, value: unknown) => {
+    const listeners = handlers.get(key) ?? []
+    for (const listener of listeners) {
+      try {
+        listener(value)
+      } catch {
+        // One broken handler must not stop the others.
+      }
+    }
+  }
+  const fail = (error: unknown) => {
+    if (disposed) return
+    const message = error instanceof Error ? error.message : String(error)
+    commit(withNotice(get(), 'error', message))
+    emit('error', message)
+  }
+  /** Show a refused receipt that no event reports. See `isNotExposed`. */
+  const refused = (result: unknown) => {
+    if (disposed || !isNotExposed(result)) return
+    const text = notAccepted('not_exposed')
+    commit(withNotice(get(), 'rejected', text))
+    emit('error', text)
+  }
+  const alive = () => {
+    if (disposed) throw new Error('The session view is disposed.')
+  }
+  /** Run a source call, and show a refused receipt or an error. */
+  const act = async (call: () => Promise<Receipt>) => {
+    alive()
+    await call().then(refused, fail)
+  }
+  const missing = (what: string) =>
+    Promise.reject(new Error(`This view source cannot ${what}.`))
+  /** A local operation reports failures as events. A remote call that throws did not arrive. */
+  const settle = (result: unknown) => {
+    if (isOperation(result)) {
+      result.then(undefined, () => {})
+      return
+    }
+    Promise.resolve(result).then(refused, fail)
+  }
+
+  const fetchUrl = async (id: string) => {
+    if (!source.mediaUrl) return
+    try {
+      const { url, expiresAt } = await source.mediaUrl(id)
+      const part = mediaParts.get(id)
+      if (disposed || !part) return
+      if (url !== undefined) mediaParts.set(id, { ...part, url })
+      commit(get())
+      if (expiresAt === undefined) return
+      const left = expiresAt - Date.now()
+      // ponytail: at least half the time left, and at least a second, so a
+      // URL with a short life does not refresh in a loop.
+      const delay = Math.max(left - URL_REFRESH_EARLY, left / 2, 1000)
+      urlRefreshes.set(
+        id,
+        setTimeout(() => void fetchUrl(id), delay),
+      )
+    } catch (error) {
+      fail(error)
+    }
+  }
+  /** The view's own part for a media id: it loads from the source and gets a url once. */
+  const mediaActions = (part: MediaPart) => {
+    shownMedia.add(part.id)
+    const known = mediaParts.get(part.id)
+    if (known) return known
+    const { id } = part
+    const shown: MediaPart = {
+      ...part,
+      load: () =>
+        source.loadMedia
+          ? source.loadMedia(id)
+          : Promise.reject(new Error('This session source cannot load media.')),
+    }
+    mediaParts.set(id, shown)
+    void fetchUrl(id)
+    return shown
+  }
+  const partsWithActions = (parts: Array<ViewPart>): Array<ViewPart> =>
+    keep(
+      parts,
+      parts.map((part) => {
+        if (part.type === 'media') return mediaActions(part)
+        if (part.type !== 'agent') return part
+        const inner = partsWithActions(part.parts)
+        return inner === part.parts ? part : { ...part, parts: inner }
+      }),
+    )
+  const messageWithActions = (message: ViewMessage) => {
+    if (message.role === 'assistant') {
+      const parts = partsWithActions(message.parts)
+      return parts === message.parts ? message : { ...message, parts }
+    }
+    if (message.role !== 'user' || !message.media) return message
+    const media = keep(message.media, message.media.map(mediaActions))
+    return media === message.media ? message : { ...message, media }
+  }
+  // ponytail: this walks every message on each commit. Track new media ids
+  // instead if a long session gets slow.
+  const withMediaActions = (state: SessionViewState) => {
+    const messages = keep(
+      state.messages,
+      state.messages.map(messageWithActions),
+    )
+    return messages === state.messages ? state : { ...state, messages }
+  }
+
+  /**
+   * Keep the answer to an item of `open`. One resume must answer every open
+   * interrupt, so it goes when each approval and client tool has an answer.
+   */
+  const answer = (
+    open: ReadonlyArray<{ id: string }>,
+    entry: RunAgentResumeItem,
+  ) => {
+    alive()
+    const id = entry.interruptId
+    const isDecided =
+      resolving || decisions.has(id) || !open.some((item) => item.id === id)
+    if (isDecided) return
+    decisions.set(id, entry)
+    const { approvals, clientTools, interrupts } = get()
+    const waiting = [...approvals, ...clientTools, ...interrupts]
+    const resume = waiting.flatMap((item) => decisions.get(item.id) ?? [])
+    if (resume.length < waiting.length) return
+    decisions.clear()
+    resolving = true
+    commit({ ...get(), approvals: [], clientTools: [], interrupts: [] })
+    void source
+      .resolve(resume)
+      .then(undefined, fail)
+      .finally(() => {
+        resolving = false
+        refreshSnapshot()
+      })
+  }
+  /** `payload` is a `ToolApprovalResolution`: a boolean or an object. */
+  const decide = (id: string, payload: unknown) =>
+    answer(get().approvals, { interruptId: id, status: 'resolved', payload })
+  const approvedWith = (options?: ApproveOptions) =>
+    options ? { ...options, approved: true } : true
+  const rejectedWith = (payload?: unknown) =>
+    payload === undefined ? false : { approved: false, payload }
+  const decideAll = (approved: boolean) => {
+    alive()
+    const open = get().approvals
+    for (const item of open) decide(item.id, approved)
+  }
+
+  const factory: ItemFactory = {
+    approval: (interrupt, call) => {
+      // A call the view has not seen, for example in a reloaded child agent:
+      // the binding has its name and arguments.
+      const binding = readUnopenedInterruptBinding(interrupt)
+      const bound = binding?.kind === 'tool-approval' ? binding : undefined
+      return {
+        id: interrupt.id,
+        ...(interrupt.toolCallId ? { toolCallId: interrupt.toolCallId } : {}),
+        tool: call?.name ?? bound?.toolName ?? interrupt.message ?? 'tool',
+        args: call?.args ?? bound?.originalArgs,
+        ...(interrupt.message ? { message: interrupt.message } : {}),
+        approve: (options) => decide(interrupt.id, approvedWith(options)),
+        reject: (payload) => decide(interrupt.id, rejectedWith(payload)),
+      }
+    },
+    interrupt: (interrupt) => {
+      const open = () => get().interrupts
+      const payload = interrupt.metadata?.['tanstack:interruptPayload']
+      const { message, toolCallId, subagentRunId, responseSchema } = interrupt
+      const item: ViewInterrupt = {
+        id: interrupt.id,
+        reason: interrupt.reason,
+        ...(message ? { message } : {}),
+        ...(toolCallId ? { toolCallId } : {}),
+        ...(subagentRunId ? { subagentRunId } : {}),
+        ...(responseSchema ? { responseSchema } : {}),
+        ...(payload !== undefined ? { payload } : {}),
+        resolve: (value) =>
+          answer(open(), {
+            interruptId: interrupt.id,
+            status: 'resolved',
+            payload: value,
+          }),
+        cancel: () =>
+          answer(open(), { interruptId: interrupt.id, status: 'cancelled' }),
+      }
+      return item
+    },
+    clientTool: (interrupt, call) => {
+      const binding = readUnopenedInterruptBinding(interrupt)
+      const open = () => get().clientTools
+      return {
+        id: interrupt.id,
+        ...(interrupt.toolCallId ? { toolCallId: interrupt.toolCallId } : {}),
+        tool:
+          call?.name ??
+          (binding?.kind === 'client-tool-execution'
+            ? binding.toolName
+            : 'tool'),
+        args: call?.args ?? interrupt.metadata?.input,
+        resolve: (output) =>
+          answer(open(), {
+            interruptId: interrupt.id,
+            status: 'resolved',
+            payload: output,
+          }),
+        // The output-error form the chat engine reads for a failed client tool.
+        fail: (message) =>
+          answer(open(), {
+            interruptId: interrupt.id,
+            status: 'resolved',
+            payload: { error: message },
+            metadata: { tanstack: { state: 'output-error' } },
+          }),
+      }
+    },
+    question: (question) => ({
+      id: question.questionId,
+      message: question.message,
+      ...(question.schema ? { schema: question.schema } : {}),
+      ...(question.secret ? { secret: true } : {}),
+      ...(question.url ? { url: question.url } : {}),
+      answer: (value) => {
+        alive()
+        return source.answer({ questionId: question.questionId, value })
+      },
+    }),
+    agent: (operation) => ({
+      ...operation,
+      send: (message, options) => {
+        alive()
+        if (!source.sendToAgent) {
+          return Promise.reject(
+            new Error('This view source cannot send messages to agents.'),
+          )
+        }
+        return source.sendToAgent({
+          operationId: operation.id,
+          message,
+          ...(options?.mode ? { mode: options.mode } : {}),
+        })
+      },
+      cancel: () => {
+        alive()
+        return source.cancel(operation.id)
+      },
+    }),
+  }
+
+  const takeSnapshot = (snapshot: SessionSnapshot, initial = false) => {
+    const before = get()
+    const next = applySnapshot(before, snapshot, factory, { initial })
+    commit(next)
+    for (const approval of next.approvals)
+      if (!before.approvals.includes(approval)) emit('approval', approval)
+    for (const call of next.clientTools)
+      if (!before.clientTools.includes(call)) emit('clientTool', call)
+    for (const item of next.interrupts)
+      if (!before.interrupts.includes(item)) emit('interrupt', item)
+    for (const signIn of next.signIns)
+      if (!before.signIns.includes(signIn)) emit('signIn', signIn)
+    for (const question of next.questions)
+      if (!before.questions.includes(question)) emit('question', question)
+  }
+
+  const refreshSnapshot = coalesce(async () => {
+    try {
+      const snapshot = await source.snapshot()
+      if (!disposed) takeSnapshot(snapshot)
+    } catch (error) {
+      fail(error)
+    }
+  })
+  const refreshDescription = coalesce(async () => {
+    try {
+      const description = await source.describe()
+      if (!disposed) commit(applyDescription(get(), description))
+    } catch (error) {
+      fail(error)
+    }
+  })
+
+  /**
+   * Fill the agent parts `ids` that the saved messages made, from the saved
+   * messages of each child, then the nested children those hold.
+   */
+  const loadAgents = async (agents: Array<AgentPart>): Promise<void> => {
+    if (!source.agentTranscript) return
+    // ponytail: every child loads at start. Load on demand if long sessions
+    // get slow.
+    await Promise.all(
+      agents.map(async ({ id }) => {
+        // A continued child has one id for each of its calls.
+        if (loadedAgents.has(id)) return
+        loadedAgents.add(id)
+        try {
+          const messages = (await source.agentTranscript?.(id)) ?? []
+          const parts = agentPartsFrom(messages)
+          if (disposed) return
+          // A child that failed before its first message has only its card.
+          commit(withAgentParts(get(), id, parts, endOf(messages)))
+          await loadAgents(emptyAgentsIn([{ id, role: 'assistant', parts }]))
+        } catch (error) {
+          fail(error)
+        }
+      }),
+    )
+  }
+
+  // A revert changes which saved messages show. The session is idle then.
+  const refreshTranscript = coalesce(async () => {
+    try {
+      const transcript = await source.transcript()
+      if (disposed) return
+      const messages = messagesFromTranscript(transcript)
+      commit({ ...get(), messages })
+      loadedAgents.clear()
+      await loadAgents(emptyAgentsIn(messages))
+    } catch (error) {
+      fail(error)
+    }
+  })
+
+  const fire = (
+    entry: SessionEvent,
+    before: SessionViewState,
+    after: SessionViewState,
+  ) => {
+    const { event } = entry
+    if (event.type === EventType.TOOL_CALL_START)
+      emit('toolCall', { id: event.toolCallId, name: event.toolCallName })
+    if (event.type === EventType.SUBAGENT_STARTED) {
+      const name = event.name ?? 'agent'
+      agentNames.set(event.subagentRunId, name)
+      emit('agent', { id: event.subagentRunId, name, status: 'running' })
+    }
+    if (
+      event.type === EventType.SUBAGENT_FINISHED ||
+      event.type === EventType.SUBAGENT_ERROR
+    ) {
+      emit('agent', {
+        id: event.subagentRunId,
+        name: agentNames.get(event.subagentRunId) ?? 'agent',
+        status: event.type === EventType.SUBAGENT_FINISHED ? 'done' : 'failed',
+      })
+    }
+    const isLeadError =
+      event.type === EventType.RUN_ERROR &&
+      !('subagentRunId' in event && event.subagentRunId)
+    if (isLeadError) emit('error', `Error: ${event.message}`)
+    if (event.type === EventType.CUSTOM) {
+      const value: Record<string, unknown> =
+        typeof event.value === 'object' && event.value !== null
+          ? event.value
+          : {}
+      const operationId = String(value.operationId)
+      if (event.name === HARNESS_EVENTS.inputRejected)
+        emit('error', notAccepted(value.reason))
+      if (
+        event.name === HARNESS_EVENTS.pluginEvent &&
+        typeof value.name === 'string'
+      )
+        emit(`plugin:${value.name}`, value.value)
+      if (
+        event.name === HARNESS_EVENTS.operationStarted &&
+        value.kind === 'chat'
+      )
+        chatTurns.add(operationId)
+      const isTurnEnd =
+        event.name === HARNESS_EVENTS.operationFinished &&
+        chatTurns.delete(operationId)
+      // The resolve of an interrupt runs as a new chat turn.
+      if (isTurnEnd && value.status !== 'interrupted')
+        emit('turnEnd', { operationId })
+      const isDescriptionChange =
+        event.name === HARNESS_EVENTS.configChanged ||
+        event.name === HARNESS_EVENTS.settingsChanged ||
+        event.name === HARNESS_EVENTS.commandsChanged ||
+        event.name === HARNESS_EVENTS.reloaded
+      if (isDescriptionChange) refreshDescription()
+      if (event.name === HARNESS_EVENTS.revert) refreshTranscript()
+    }
+    for (const signIn of after.signIns)
+      if (!before.signIns.includes(signIn)) emit('signIn', signIn)
+  }
+
+  const read = async (from: Cursor | undefined) => {
+    try {
+      const entries = source.events({
+        ...(from ? { from } : {}),
+        signal: reader.signal,
+        onConnection: (connection) => commit({ ...get(), connection }),
+      })
+      for await (const entry of entries) {
+        if (disposed) return
+        for (const ready of replayed(entry)) apply(ready)
+      }
+    } catch (error) {
+      fail(error)
+    }
+    if (!disposed) commit({ ...get(), connection: 'closed' })
+  }
+
+  const apply = (entry: SessionEvent) => {
+    if (disposed) return
+    const before = get()
+    const after = applyEvent(before, entry)
+    commit(after)
+    fire(entry, before, after)
+    if (changesSnapshot(entry)) refreshSnapshot()
+  }
+
+  /**
+   * An event of the saved transcript: `'skip'` for a part the transcript
+   * shows, `'boundary'` for a tool result of a saved call (it still applies).
+   * Only replayed events can be saved: a background child or a continued
+   * child keeps its id, and its later events are new.
+   */
+  const isSaved = ({ event }: SessionEvent) => {
+    const child = subagentOf(event)
+    // A child of a saved child is saved too.
+    const isSavedChild =
+      event.type === EventType.SUBAGENT_STARTED &&
+      saved.has(event.parentSubagentRunId ?? '')
+    if (isSavedChild) saved.add(event.subagentRunId)
+    if (child !== undefined) return saved.has(child) ? 'skip' : undefined
+    const id =
+      event.type === EventType.TEXT_MESSAGE_CONTENT
+        ? event.messageId
+        : event.type === EventType.TOOL_CALL_START ||
+            event.type === EventType.TOOL_CALL_ARGS ||
+            event.type === EventType.TOOL_CALL_END ||
+            event.type === EventType.TOOL_CALL_RESULT
+          ? event.toolCallId
+          : undefined
+    if (id === undefined || !saved.has(id)) return undefined
+    return event.type === EventType.TOOL_CALL_RESULT ? 'boundary' : 'skip'
+  }
+
+  /** The held reasoning of `operationId`, out of `held`. */
+  const takeHeld = (operationId: string) => {
+    const out = held.filter((item) => item.operationId === operationId)
+    held = held.filter((item) => item.operationId !== operationId)
+    return out
+  }
+
+  /**
+   * The events to apply now. An operation that ran when the view opened
+   * replays from its start. Events of other operations in that range are in
+   * the transcript already, and so are the saved model calls of the running
+   * turn: their text and tool calls are dropped by id. A model call can also
+   * be saved between the snapshot and the transcript reads, so lead events
+   * after the replay are checked too. Reasoning has no saved id, so replayed
+   * lead reasoning waits for the next text or tool call of its operation, and
+   * goes with it when that one is saved. A retry drops it. The end of its
+   * operation shows it.
+   */
+  const replayed = (entry: SessionEvent): Array<SessionEvent> => {
+    const inReplay = Number(entry.cursor) <= replayEnd
+    const { event } = entry
+    const operation = entry.operationId
+    const isLead = subagentOf(event) === undefined
+    if (inReplay && !replayOps.has(operation)) return []
+    if (isRetry(entry)) {
+      takeHeld(operation)
+      return [entry]
+    }
+    const isWaiting = held.some((item) => item.operationId === operation)
+    if (
+      isLead &&
+      event.type.startsWith('REASONING') &&
+      (inReplay || isWaiting)
+    ) {
+      held.push(entry)
+      return []
+    }
+    const found = inReplay || isLead ? isSaved(entry) : undefined
+    const isCall = isLead && CALL_EVENTS.has(event.type)
+    const waiting = isCall || isEnd(entry) ? takeHeld(operation) : []
+    if (found) return found === 'skip' ? [] : [entry]
+    return [...waiting, entry]
+  }
+
+  const ready = (async () => {
+    const describing = Promise.resolve(source.describe()).catch(
+      (error: unknown) => {
+        fail(error)
+        return undefined
+      },
+    )
+    // The snapshot before the transcript: a turn that ends between the two
+    // reads is in the transcript, and `replayed` drops its events.
+    const snapshot = await Promise.resolve(source.snapshot()).catch(
+      (error: unknown) => {
+        fail(error)
+        return undefined
+      },
+    )
+    const transcript = await source.transcript().catch((error: unknown) => {
+      fail(error)
+      return []
+    })
+    const description = await describing
+    if (disposed) return
+    // History first, then anything a UI added before ready.
+    commit({
+      ...get(),
+      messages: [...messagesFromTranscript(transcript), ...get().messages],
+    })
+    if (snapshot) takeSnapshot(snapshot, true)
+    if (description) commit(applyDescription(get(), description))
+    saved = transcriptIds(transcript)
+    // ponytail: a cursor is a sequence number in both feeds (`feed.ts`,
+    // `log.ts`), so `Number` orders them.
+    const starts = (snapshot?.activeOperations ?? []).flatMap((operation) =>
+      operation.startedCursor === undefined
+        ? []
+        : [Number(operation.startedCursor)],
+    )
+    const head = Number(snapshot?.cursor ?? 0)
+    const from = Math.min(head, ...starts)
+    if (from < head) {
+      replayEnd = head
+      replayOps = new Set(snapshot?.activeOperations.map((item) => item.id))
+    }
+    // ponytail: a background child that runs now can save a model call
+    // before its saved messages load, and that call then shows twice. Drop
+    // live parts by id if that shows up.
+    void loadAgents(emptyAgentsIn(get().messages))
+    void read(snapshot ? String(from) : undefined)
+  })()
+
+  const on: SessionView['on'] = (key, handler) => {
+    const name = typeof key === 'string' ? key : `plugin:${key.name}`
+    // A plugin event value is JSON from the session. Its type comes from the
+    // `PluginEvent` the caller passes, as with `ctx.on` in a plugin.
+    const listener = (value: unknown) => handler(value as never)
+    let set = handlers.get(name)
+    if (!set) {
+      set = new Set()
+      handlers.set(name, set)
+    }
+    set.add(listener)
+    return () => set.delete(listener)
+  }
+
+  const view: SessionView = {
+    store,
+    ready,
+    send: async (text, attachments = []) => {
+      alive()
+      const line = text.trim()
+      if (line === '' && attachments.length === 0) return
+      if (line.startsWith('/')) {
+        const [name = '', ...rest] = line.slice(1).split(' ')
+        const input = rest.join(' ').trim()
+        settle(source.command(name, input === '' ? undefined : input))
+        return
+      }
+      commit(withUserMessage(get(), line, attachments))
+      const message = userInput(line, attachments)
+      if (get().status === 'running') {
+        await source.steer(message).then(refused, fail)
+        return
+      }
+      settle(source.prompt(message))
+    },
+    followUp: async (text, attachments = []) => {
+      alive()
+      const line = text.trim()
+      if (line === '' && attachments.length === 0) return
+      commit(withUserMessage(get(), line, attachments))
+      const message = userInput(line, attachments)
+      await act(() =>
+        source.followUp ? source.followUp(message) : missing('follow up'),
+      )
+    },
+    continue: async () => {
+      alive()
+      settle(source.continue ? source.continue() : missing('continue'))
+    },
+    upload: (body, info) => {
+      alive()
+      if (source.upload) return source.upload(body, info)
+      if (source.putMedia) return source.putMedia(body, info)
+      return Promise.reject(new Error('This view source cannot store media.'))
+    },
+    command: async (name, input) => {
+      alive()
+      settle(source.command(name, input))
+    },
+    setConfig: (change) => act(() => source.setConfig(change)),
+    configure: (settings) =>
+      act(() =>
+        source.configure ? source.configure(settings) : missing('configure'),
+      ),
+    cancel: (operationId) => act(() => source.cancel(operationId)),
+    cancelInput: (inputId) =>
+      act(() =>
+        source.cancelInput
+          ? source.cancelInput(inputId)
+          : missing('cancel inputs'),
+      ),
+    setDelivery: (change) =>
+      act(() =>
+        source.setDelivery
+          ? source.setDelivery(change)
+          : missing('move inputs'),
+      ),
+    reset: (note) =>
+      act(() => (source.reset ? source.reset(note) : missing('reset'))),
+    revert: (messageId) =>
+      act(() => (source.revert ? source.revert(messageId) : missing('revert'))),
+    unrevert: () =>
+      act(() => (source.unrevert ? source.unrevert() : missing('unrevert'))),
+    approve: (id, options) => decide(id, approvedWith(options)),
+    reject: (id, payload) => decide(id, rejectedWith(payload)),
+    approveAll: () => decideAll(true),
+    rejectAll: () => decideAll(false),
+    notice: (text) => {
+      alive()
+      commit(withNotice(get(), 'ui', text))
+    },
+    on,
+    dispose: () => {
+      if (disposed) return
+      commit({ ...get(), connection: 'closed' })
+      disposed = true
+      reader.abort()
+      for (const timer of urlRefreshes.values()) clearTimeout(timer)
+      urlRefreshes.clear()
+    },
+  }
+  return view
+}
diff --git a/packages/ai-harness/src/view/reduce.ts b/packages/ai-harness/src/view/reduce.ts
new file mode 100644
index 0000000000..f5a59bed89
--- /dev/null
+++ b/packages/ai-harness/src/view/reduce.ts
@@ -0,0 +1,1009 @@
+import { EventType, readUnopenedInterruptBinding } from '@tanstack/ai'
+import { isMediaRecord, mediaIdOf, mediaOfMessage } from '../media-ref'
+import { HARNESS_EVENTS } from '../types'
+import type { Interrupt, ModelMessage, StreamChunk } from '@tanstack/ai'
+import type { SessionDescription, SessionSnapshot } from '../session/index'
+import type { SessionEvent } from '../types'
+import type {
+  AgentPart,
+  Approval,
+  ClientToolCall,
+  MediaPart,
+  NoticeKind,
+  SessionViewState,
+  SignIn,
+  ToolCallPart,
+  ViewAgent,
+  ViewInterrupt,
+  ViewMessage,
+  ViewPart,
+  ViewQuestion,
+} from './types'
+
+const COMMAND_RESULT = 'harness.command.result'
+
+/** Events that change the parts of the current turn. */
+const TURN_EVENTS: ReadonlySet<string> = new Set([
+  EventType.TEXT_MESSAGE_START,
+  EventType.TEXT_MESSAGE_CONTENT,
+  EventType.REASONING_MESSAGE_CONTENT,
+  EventType.TOOL_CALL_START,
+  EventType.TOOL_CALL_ARGS,
+  EventType.TOOL_CALL_END,
+  EventType.TOOL_CALL_RESULT,
+  EventType.SUBAGENT_STARTED,
+  EventType.SUBAGENT_FINISHED,
+  EventType.SUBAGENT_ERROR,
+])
+
+/** Makes the items that carry actions. The view owns the actions. */
+export interface ItemFactory {
+  approval: (interrupt: Interrupt, call: ToolCallPart | undefined) => Approval
+  clientTool: (
+    interrupt: Interrupt,
+    call: ToolCallPart | undefined,
+  ) => ClientToolCall
+  question: (
+    question: SessionSnapshot['pendingQuestions'][number],
+  ) => ViewQuestion
+  interrupt: (interrupt: Interrupt) => ViewInterrupt
+  agent: (operation: { id: string; name: string }) => ViewAgent
+}
+
+/** The state of a view before it reads anything from its session. */
+export function emptyState(): SessionViewState {
+  return {
+    threadId: '',
+    status: 'idle',
+    connection: 'open',
+    messages: [],
+    approvals: [],
+    clientTools: [],
+    interrupts: [],
+    questions: [],
+    signIns: [],
+    agents: [],
+    queuedTurns: 0,
+    waitingInputs: [],
+    commands: [],
+    config: [],
+    tools: [],
+    models: [],
+    plugins: {},
+  }
+}
+
+function parseJson(text: string): unknown {
+  if (text === '') return undefined
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+function textOf(content: ModelMessage['content']): string {
+  if (typeof content === 'string') return content
+  if (!content) return ''
+  return content
+    .map((part) => (part.type === 'text' ? part.content : ''))
+    .join('')
+}
+
+export function subagentOf(event: StreamChunk): string | undefined {
+  return 'subagentRunId' in event && typeof event.subagentRunId === 'string'
+    ? event.subagentRunId
+    : undefined
+}
+
+/** Custom event values and snapshots are plain JSON objects. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function recordOf(value: unknown): Record<string, unknown> {
+  return isRecord(value) ? value : {}
+}
+
+/** The fields of a media part that come from its record. */
+type MediaInfo = Omit<MediaPart, 'type' | 'url' | 'load'>
+
+// ponytail: the reducer keeps only data. The view swaps this `load` for one
+// that reads from its source, and adds the `url`.
+const notInView = () =>
+  Promise.reject(new Error('Only a session view can load media bytes.'))
+
+function mediaView(media: MediaInfo) {
+  const part: MediaPart = {
+    type: 'media',
+    id: media.id,
+    kind: media.kind,
+    mimeType: media.mimeType,
+    name: media.name,
+    size: media.size,
+    load: notInView,
+  }
+  return part
+}
+
+/**
+ * Media parts for the `harness-media:` parts of a saved user message. The
+ * name and size come from the records in `metadata.harness.media`.
+ */
+function userMedia(message: ModelMessage) {
+  const { content } = message
+  if (typeof content === 'string' || !content) return []
+  const records = mediaOfMessage(message)
+  return content.flatMap((part) => {
+    const id = mediaIdOf(part)
+    if (id === undefined || part.type === 'text') return []
+    // A message saved without the records keeps only the id and MIME type of
+    // a part, so the name is the id and the size is 0.
+    const record = records.find((media) => media.id === id) ?? {
+      id,
+      kind: part.type,
+      mimeType: part.source.mimeType ?? '',
+      name: id,
+      size: 0,
+    }
+    return [mediaView(record)]
+  })
+}
+
+/** The notice for a `session.reset()`: the model starts again from here. */
+function resetNotice(note: unknown) {
+  return typeof note === 'string'
+    ? `The context was reset. The model starts from this note: ${note}`
+    : 'The context was reset. The model sees only what comes after this.'
+}
+
+/** The notice text for a refused input. */
+export const notAccepted = (reason: unknown) =>
+  `Not accepted: ${String(reason ?? 'unknown reason')}`
+
+/** Add a notice line at the end of the messages. */
+export function withNotice(
+  state: SessionViewState,
+  kind: NoticeKind,
+  text: string,
+): SessionViewState {
+  const message: ViewMessage = {
+    id: `notice-${state.messages.length}`,
+    role: 'notice',
+    kind,
+    text,
+  }
+  return { ...state, messages: [...state.messages, message] }
+}
+
+/** Add a user message, with the files the user sent, at the end of the messages. */
+export function withUserMessage(
+  state: SessionViewState,
+  text: string,
+  media: ReadonlyArray<MediaInfo> = [],
+): SessionViewState {
+  const message: ViewMessage = {
+    id: `user-${state.messages.length}`,
+    role: 'user',
+    text,
+    ...(media.length > 0 ? { media: media.map(mediaView) } : {}),
+  }
+  return { ...state, messages: [...state.messages, message] }
+}
+
+function appendText(
+  parts: Array<ViewPart>,
+  type: 'text' | 'reasoning',
+  delta: string,
+): Array<ViewPart> {
+  if (delta === '') return parts
+  const last = parts.at(-1)
+  if (last?.type === type) {
+    return [...parts.slice(0, -1), { type, text: last.text + delta }]
+  }
+  return [...parts, { type, text: delta }]
+}
+
+function mapToolCall(
+  parts: Array<ViewPart>,
+  id: string,
+  change: (call: ToolCallPart) => ToolCallPart,
+): Array<ViewPart> {
+  const index = parts.findIndex(
+    (part) => part.type === 'tool-call' && part.id === id,
+  )
+  const part = parts[index]
+  if (part?.type !== 'tool-call') return parts
+  const next = [...parts]
+  next[index] = change(part)
+  return next
+}
+
+function findAgent(
+  parts: ReadonlyArray<ViewPart>,
+  id: string,
+): AgentPart | undefined {
+  for (const part of parts) {
+    if (part.type !== 'agent') continue
+    if (part.id === id) return part
+    const inner = findAgent(part.parts, id)
+    if (inner) return inner
+  }
+  return undefined
+}
+
+function mapAgent(
+  parts: Array<ViewPart>,
+  id: string,
+  change: (agent: AgentPart) => AgentPart,
+): Array<ViewPart> {
+  let found = false
+  let changed = false
+  const next = parts.map((part) => {
+    if (part.type !== 'agent' || found) return part
+    if (part.id === id) {
+      found = true
+      const updated = change(part)
+      if (updated !== part) changed = true
+      return updated
+    }
+    const inner = mapAgent(part.parts, id, change)
+    if (inner === part.parts) return part
+    found = true
+    changed = true
+    return { ...part, parts: inner }
+  })
+  return changed ? next : parts
+}
+
+/** Text, reasoning, and tool call events of one agent (the lead or a child). */
+function applyOwn(parts: Array<ViewPart>, event: StreamChunk): Array<ViewPart> {
+  // Each model call gets its own text part, so a retry can drop one call.
+  if (event.type === EventType.TEXT_MESSAGE_START)
+    return parts.at(-1)?.type === 'text'
+      ? [...parts, { type: 'text', text: '' }]
+      : parts
+  if (event.type === EventType.TEXT_MESSAGE_CONTENT)
+    return appendText(parts, 'text', event.delta)
+  if (event.type === EventType.REASONING_MESSAGE_CONTENT)
+    return appendText(parts, 'reasoning', event.delta)
+  if (event.type === EventType.TOOL_CALL_START) {
+    if (
+      parts.some(
+        (part) => part.type === 'tool-call' && part.id === event.toolCallId,
+      )
+    )
+      return parts
+    return [
+      ...parts,
+      {
+        type: 'tool-call',
+        id: event.toolCallId,
+        name: event.toolCallName,
+        argsText: '',
+        args: undefined,
+        status: 'running',
+      },
+    ]
+  }
+  if (event.type === EventType.TOOL_CALL_ARGS)
+    return mapToolCall(parts, event.toolCallId, (call) => ({
+      ...call,
+      argsText: call.argsText + event.delta,
+    }))
+  if (event.type === EventType.TOOL_CALL_END)
+    return mapToolCall(parts, event.toolCallId, (call) => ({
+      ...call,
+      // An adapter can send the parsed input with no ARGS deltas.
+      args:
+        call.argsText === '' && event.input !== undefined
+          ? event.input
+          : parseJson(call.argsText),
+    }))
+  if (event.type === EventType.TOOL_CALL_RESULT)
+    return mapToolCall(parts, event.toolCallId, (call) => ({
+      ...call,
+      // A failed call shows as failed live too, as it does from the transcript.
+      status:
+        recordOf(recordOf(event.metadata).tanstack).state === 'output-error'
+          ? 'failed'
+          : 'done',
+      // Content parts (a multimodal result) stay as they are.
+      result:
+        typeof event.content === 'string'
+          ? parseJson(event.content)
+          : event.content,
+    }))
+  return parts
+}
+
+/** Route an event to the lead's parts or to the child agent it belongs to. */
+function applyToParts(
+  parts: Array<ViewPart>,
+  event: StreamChunk,
+): Array<ViewPart> {
+  const child = subagentOf(event)
+  if (child === undefined) return applyOwn(parts, event)
+  if (event.type === EventType.SUBAGENT_STARTED) {
+    if (findAgent(parts, child)) return parts
+    const agent: AgentPart = {
+      type: 'agent',
+      id: child,
+      name: event.name ?? 'agent',
+      status: 'running',
+      parts: [],
+    }
+    const parent = event.parentSubagentRunId
+    if (parent !== undefined && findAgent(parts, parent)) {
+      return mapAgent(parts, parent, (owner) => ({
+        ...owner,
+        parts: [...owner.parts, agent],
+      }))
+    }
+    return [...parts, agent]
+  }
+  return mapAgent(parts, child, (agent) => applyToChild(agent, event))
+}
+
+/** One event of a child agent, on its part. */
+function applyToChild(agent: AgentPart, event: StreamChunk): AgentPart {
+  if (event.type === EventType.SUBAGENT_STARTED)
+    return agent.status === 'running' ? agent : { ...agent, status: 'running' }
+  if (event.type === EventType.SUBAGENT_FINISHED) {
+    const { result } = event
+    return {
+      ...agent,
+      status: 'done',
+      ...(result !== undefined ? { result } : {}),
+    }
+  }
+  if (event.type === EventType.SUBAGENT_ERROR)
+    return { ...agent, status: 'failed', error: event.message }
+  const inner = applyOwn(agent.parts, event)
+  return inner === agent.parts ? agent : { ...agent, parts: inner }
+}
+
+/**
+ * An event of a child that the turn does not show, on the part of the
+ * message that does: a background child that a saved message shows.
+ */
+function applyToShownChild(
+  state: SessionViewState,
+  child: string,
+  event: StreamChunk,
+): SessionViewState {
+  const messages = keep(
+    state.messages,
+    state.messages.map((message) => {
+      if (message.role !== 'assistant') return message
+      const parts = mapAgent(message.parts, child, (agent) =>
+        applyToChild(agent, event),
+      )
+      return parts === message.parts ? message : { ...message, parts }
+    }),
+  )
+  return messages === state.messages ? state : { ...state, messages }
+}
+
+/** Change the assistant message of one turn. It is created on its first part. */
+function updateTurn(
+  state: SessionViewState,
+  operationId: string,
+  change: (parts: Array<ViewPart>) => Array<ViewPart>,
+): SessionViewState {
+  const id = `turn-${operationId}`
+  const index = state.messages.findLastIndex((message) => message.id === id)
+  const current = state.messages[index]
+  const parts = current?.role === 'assistant' ? current.parts : []
+  const next = change(parts)
+  if (next === parts) return state
+  const message: ViewMessage = { id, role: 'assistant', parts: next }
+  if (index < 0) return { ...state, messages: [...state.messages, message] }
+  const messages = [...state.messages]
+  messages[index] = message
+  return { ...state, messages }
+}
+
+/**
+ * The parts without what the model call that failed streamed: its running
+ * tool calls, its text part, and the reasoning before that text. The text of
+ * an earlier call is a part of its own, so it stays.
+ */
+function withoutAttempt(parts: Array<ViewPart>): Array<ViewPart> {
+  // ponytail: a failed call that streamed no text also drops the text of
+  // the call before it. Mark where each model call starts if that matters.
+  let end = parts.length
+  const at = (index: number) => parts[index - 1]
+  const isRunning = (part: ViewPart | undefined) =>
+    part?.type === 'tool-call' && part.status === 'running'
+  while (end > 0 && isRunning(at(end))) end -= 1
+  if (at(end)?.type === 'text') end -= 1
+  while (end > 0 && at(end)?.type === 'reasoning') end -= 1
+  return end === parts.length ? parts : parts.slice(0, end)
+}
+
+function addMedia(parts: Array<ViewPart>, part: MediaPart) {
+  const isShown = parts.some(
+    (item) => item.type === 'media' && item.id === part.id,
+  )
+  return isShown ? parts : [...parts, part]
+}
+
+/** Media goes in the agent part of the child that made it, else in the lead parts. */
+function withMedia(
+  state: SessionViewState,
+  operationId: string,
+  media: MediaInfo,
+  child: string | undefined,
+) {
+  const part = mediaView(media)
+  return updateTurn(state, operationId, (parts) => {
+    if (child === undefined || !findAgent(parts, child))
+      return addMedia(parts, part)
+    return mapAgent(parts, child, (agent) => {
+      const inner = addMedia(agent.parts, part)
+      return inner === agent.parts ? agent : { ...agent, parts: inner }
+    })
+  })
+}
+
+/** A lead tool result can come in a later turn (after an approval). */
+function applyToolResult(
+  state: SessionViewState,
+  event: StreamChunk,
+): SessionViewState {
+  for (let index = state.messages.length - 1; index >= 0; index -= 1) {
+    const message = state.messages[index]
+    if (message?.role !== 'assistant') continue
+    const parts = applyOwn(message.parts, event)
+    if (parts === message.parts) continue
+    const messages = [...state.messages]
+    messages[index] = { ...message, parts }
+    return { ...state, messages }
+  }
+  return state
+}
+
+function failRunning(
+  state: SessionViewState,
+  operationId: string,
+): SessionViewState {
+  return updateTurn(state, operationId, (parts) =>
+    parts.some((part) => part.type === 'tool-call' && part.status === 'running')
+      ? parts.map((part) =>
+          part.type === 'tool-call' && part.status === 'running'
+            ? { ...part, status: 'failed' }
+            : part,
+        )
+      : parts,
+  )
+}
+
+function withSignIn(state: SessionViewState, signIn: SignIn): SessionViewState {
+  return {
+    ...state,
+    signIns: [
+      ...state.signIns.filter((item) => item.connector !== signIn.connector),
+      signIn,
+    ],
+  }
+}
+
+function withConfigValue(
+  state: SessionViewState,
+  key: string,
+  value: unknown,
+): SessionViewState {
+  if (!state.config.some((entry) => entry.key === key)) return state
+  return {
+    ...state,
+    config: state.config.map((entry) =>
+      entry.key === key ? { ...entry, value } : entry,
+    ),
+  }
+}
+
+/** Fold one session event into the state. Returns `state` when nothing changes. */
+export function applyEvent(
+  state: SessionViewState,
+  entry: SessionEvent,
+): SessionViewState {
+  const { event, operationId } = entry
+  if (
+    event.type === EventType.TOOL_CALL_RESULT &&
+    subagentOf(event) === undefined
+  )
+    return applyToolResult(state, event)
+  if (TURN_EVENTS.has(event.type)) {
+    const next = updateTurn(state, operationId, (parts) =>
+      applyToParts(parts, event),
+    )
+    const child = subagentOf(event)
+    const isElsewhere =
+      next === state &&
+      child !== undefined &&
+      event.type !== EventType.SUBAGENT_STARTED
+    return isElsewhere ? applyToShownChild(state, child, event) : next
+  }
+  if (event.type === EventType.RUN_ERROR) {
+    if (subagentOf(event) !== undefined) return state
+    return failRunning(
+      withNotice(state, 'error', `Error: ${event.message}`),
+      operationId,
+    )
+  }
+  if (event.type === EventType.STATE_SNAPSHOT) {
+    const snapshot = recordOf(event.snapshot)
+    return 'plugins' in snapshot
+      ? { ...state, plugins: recordOf(snapshot.plugins) }
+      : state
+  }
+  if (event.type !== EventType.CUSTOM) return state
+  const value = recordOf(event.value)
+  if (event.name === HARNESS_EVENTS.media)
+    return isMediaRecord(value)
+      ? withMedia(state, operationId, value, value.subagentRunId)
+      : state
+  if (event.name === HARNESS_EVENTS.operationResumed)
+    return withNotice(state, 'info', 'Resumed a turn that a crash stopped.')
+  // A retry that does not continue the partial answer starts the model call
+  // again, so the text of the failed attempt goes.
+  if (event.name === HARNESS_EVENTS.turnRetry && value.continued !== true)
+    return updateTurn(state, String(value.operationId), withoutAttempt)
+  if (event.name === COMMAND_RESULT) {
+    // A finished `connect:<id>` ends the sign-in it waited for.
+    const connector =
+      typeof value.name === 'string'
+        ? /^connect:(.+)$/.exec(value.name)?.[1]
+        : undefined
+    const signedIn = connector
+      ? {
+          ...state,
+          signIns: state.signIns.filter((item) => item.connector !== connector),
+        }
+      : state
+    return typeof value.result === 'string' && value.result !== ''
+      ? withNotice(signedIn, 'command', value.result)
+      : signedIn
+  }
+  if (event.name === HARNESS_EVENTS.inputRejected)
+    return withNotice(state, 'rejected', notAccepted(value.reason))
+  if (event.name === HARNESS_EVENTS.reset)
+    return withNotice(state, 'info', resetNotice(value.note))
+  if (
+    event.name === HARNESS_EVENTS.authRequired &&
+    typeof value.connector === 'string'
+  ) {
+    return withSignIn(state, {
+      connector: value.connector,
+      ...(typeof value.url === 'string' ? { url: value.url } : {}),
+      ...(typeof value.userCode === 'string'
+        ? { userCode: value.userCode }
+        : {}),
+    })
+  }
+  if (
+    event.name === HARNESS_EVENTS.configChanged &&
+    typeof value.key === 'string'
+  )
+    return withConfigValue(state, value.key, value.value)
+  const isChatStart =
+    event.name === HARNESS_EVENTS.operationStarted && value.kind === 'chat'
+  if (isChatStart && state.signIns.length > 0) return { ...state, signIns: [] }
+  return state
+}
+
+/** The tool call `id` in `parts`, also in the parts of child agents. */
+function findCallIn(
+  parts: ReadonlyArray<ViewPart>,
+  id: string,
+): ToolCallPart | undefined {
+  for (const part of parts) {
+    if (part.type === 'tool-call' && part.id === id) return part
+    if (part.type !== 'agent') continue
+    const inner = findCallIn(part.parts, id)
+    if (inner) return inner
+  }
+  return undefined
+}
+
+function findToolCall(
+  messages: ReadonlyArray<ViewMessage>,
+  id: string | undefined,
+): ToolCallPart | undefined {
+  if (id === undefined) return undefined
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index]
+    if (message?.role !== 'assistant') continue
+    const part = findCallIn(message.parts, id)
+    if (part) return part
+  }
+  return undefined
+}
+
+/** Mark the running calls in `waiting` as `needs-approval`, also in child agents. */
+function markParts(
+  parts: Array<ViewPart>,
+  waiting: ReadonlySet<string>,
+): Array<ViewPart> {
+  return keep(
+    parts,
+    parts.map((part) => {
+      if (part.type === 'agent') {
+        const inner = markParts(part.parts, waiting)
+        return inner === part.parts ? part : { ...part, parts: inner }
+      }
+      const isWaiting =
+        part.type === 'tool-call' &&
+        part.status === 'running' &&
+        waiting.has(part.id)
+      return isWaiting ? { ...part, status: 'needs-approval' as const } : part
+    }),
+  )
+}
+
+function markWaiting(
+  messages: Array<ViewMessage>,
+  waiting: ReadonlySet<string>,
+): Array<ViewMessage> {
+  if (waiting.size === 0) return messages
+  return keep(
+    messages,
+    messages.map((message) => {
+      if (message.role !== 'assistant') return message
+      const parts = markParts(message.parts, waiting)
+      return parts === message.parts ? message : { ...message, parts }
+    }),
+  )
+}
+
+/** `old` when `next` holds the same items, so selectors see no change. */
+export function keep<T>(old: Array<T>, next: Array<T>): Array<T> {
+  return old.length === next.length &&
+    old.every((item, index) => item === next[index])
+    ? old
+    : next
+}
+
+/** The turn waits for the output of a client tool, not for a yes or no. */
+const isClientTool = (interrupt: Interrupt) =>
+  readUnopenedInterruptBinding(interrupt)?.kind === 'client-tool-execution'
+
+/** The turn waits for an answer of the interrupt's own shape. */
+const isGeneric = (interrupt: Interrupt) =>
+  readUnopenedInterruptBinding(interrupt)?.kind === 'generic' &&
+  !signInOf(interrupt)
+
+/**
+ * The sign-in a turn waits for, from `credentials.require(id, { wait: true })`.
+ * The connector's `connect:<id>` command answers it, not a yes or no.
+ */
+function signInOf(interrupt: Interrupt): SignIn | undefined {
+  if (interrupt.reason !== 'auth_required') return undefined
+  const payload = recordOf(interrupt.metadata?.['tanstack:interruptPayload'])
+  const request = recordOf(payload.request)
+  if (typeof request.connector !== 'string') return undefined
+  return {
+    connector: request.connector,
+    ...(typeof request.url === 'string' ? { url: request.url } : {}),
+  }
+}
+
+/**
+ * Take status, approvals, client tools, questions, background agents, and
+ * waiting inputs from a snapshot. Plugin state is taken only for the first
+ * snapshot. Later changes come as `STATE_SNAPSHOT` events. Returns `state`
+ * when nothing changes.
+ */
+export function applySnapshot(
+  state: SessionViewState,
+  snapshot: SessionSnapshot,
+  factory: ItemFactory,
+  options: { initial?: boolean } = {},
+): SessionViewState {
+  const approvals = keep(
+    state.approvals,
+    snapshot.pendingInterrupts
+      .filter(
+        (interrupt) =>
+          !isClientTool(interrupt) &&
+          !isGeneric(interrupt) &&
+          !signInOf(interrupt),
+      )
+      .map(
+        (interrupt) =>
+          state.approvals.find((item) => item.id === interrupt.id) ??
+          factory.approval(
+            interrupt,
+            findToolCall(state.messages, interrupt.toolCallId),
+          ),
+      ),
+  )
+  const clientTools = keep(
+    state.clientTools,
+    snapshot.pendingInterrupts
+      .filter(isClientTool)
+      .map(
+        (interrupt) =>
+          state.clientTools.find((item) => item.id === interrupt.id) ??
+          factory.clientTool(
+            interrupt,
+            findToolCall(state.messages, interrupt.toolCallId),
+          ),
+      ),
+  )
+  const interrupts = keep(
+    state.interrupts,
+    snapshot.pendingInterrupts
+      .filter(isGeneric)
+      .map(
+        (interrupt) =>
+          state.interrupts.find((item) => item.id === interrupt.id) ??
+          factory.interrupt(interrupt),
+      ),
+  )
+  // Usage changes only with a new model call.
+  const usage =
+    state.usage?.total.calls === snapshot.usage.total.calls
+      ? state.usage
+      : snapshot.usage
+  // In the snapshot too, so a sign-in that a turn waits for shows after a reload.
+  const newSignIns = snapshot.pendingInterrupts
+    .flatMap((interrupt) => signInOf(interrupt) ?? [])
+    .filter(
+      (signIn) =>
+        !state.signIns.some((item) => item.connector === signIn.connector),
+    )
+  const signIns =
+    newSignIns.length > 0 ? [...state.signIns, ...newSignIns] : state.signIns
+  const questions = keep(
+    state.questions,
+    snapshot.pendingQuestions.map(
+      (question) =>
+        state.questions.find((item) => item.id === question.questionId) ??
+        factory.question(question),
+    ),
+  )
+  const agents = keep(
+    state.agents,
+    snapshot.activeOperations
+      .filter((operation) => operation.kind === 'agent')
+      .map(
+        (operation) =>
+          state.agents.find((item) => item.id === operation.id) ??
+          factory.agent({
+            id: operation.id,
+            name: operation.agent ?? 'agent',
+          }),
+      ),
+  )
+  const waitingInputs = keep(
+    state.waitingInputs,
+    (snapshot.waitingInputs ?? []).map(
+      (input) =>
+        state.waitingInputs.find(
+          (item) =>
+            item.inputId === input.inputId && item.delivery === input.delivery,
+        ) ?? input,
+    ),
+  )
+  const waiting = new Set(
+    approvals.flatMap((item) => (item.toolCallId ? [item.toolCallId] : [])),
+  )
+  const messages = markWaiting(state.messages, waiting)
+  const plugins = options.initial ? snapshot.plugins : state.plugins
+  const isSame =
+    snapshot.threadId === state.threadId &&
+    snapshot.status === state.status &&
+    snapshot.queuedTurns === state.queuedTurns &&
+    waitingInputs === state.waitingInputs &&
+    approvals === state.approvals &&
+    clientTools === state.clientTools &&
+    interrupts === state.interrupts &&
+    usage === state.usage &&
+    signIns === state.signIns &&
+    questions === state.questions &&
+    agents === state.agents &&
+    messages === state.messages &&
+    plugins === state.plugins
+  if (isSame) return state
+  return {
+    ...state,
+    threadId: snapshot.threadId,
+    status: snapshot.status,
+    queuedTurns: snapshot.queuedTurns,
+    waitingInputs,
+    approvals,
+    clientTools,
+    interrupts,
+    usage,
+    signIns,
+    questions,
+    agents,
+    messages,
+    plugins,
+  }
+}
+
+/** Take the commands, config entries, and tools from a session description. */
+export function applyDescription(
+  state: SessionViewState,
+  description: SessionDescription,
+): SessionViewState {
+  return {
+    ...state,
+    commands: description.commands,
+    config: description.config,
+    tools: description.tools,
+    models: description.models ?? [],
+    settings: description.settings,
+  }
+}
+
+/**
+ * Messages for a saved transcript. Tool results fill in their tool calls.
+ * The media a turn made (`metadata.harness.media`) goes at the end of its
+ * assistant message.
+ */
+export function messagesFromTranscript(
+  messages: ReadonlyArray<ModelMessage>,
+): Array<ViewMessage> {
+  const result: Array<ViewMessage> = []
+  messages.forEach((message, index) => {
+    const id = message.id ?? `history-${index}`
+    const harness = recordOf(message.metadata?.harness)
+    // The harness sent a wake message (a background job ended), not the
+    // user. The live view never showed it, so a reload does not either.
+    if (message.role === 'user' && harness.wake === true) return
+    // The note of a 'continue' retry is from the harness too.
+    const tanstack = recordOf(message.metadata?.tanstack)
+    if (message.role === 'user' && tanstack.synthetic === true) return
+    // The marker of a `session.reset()` shows as a notice, not a message.
+    const reset = harness.reset
+    if (message.role === 'user' && isRecord(reset)) {
+      result.push({
+        id,
+        role: 'notice',
+        kind: 'info',
+        text: resetNotice(reset.note),
+      })
+      return
+    }
+    if (message.role === 'user') {
+      const media = userMedia(message)
+      result.push({
+        id,
+        role: 'user',
+        text: textOf(message.content),
+        ...(media.length > 0 ? { media } : {}),
+      })
+      return
+    }
+    if (message.role === 'assistant') {
+      const parts: Array<ViewPart> = []
+      const thoughts = message.thinking ?? []
+      for (const thought of thoughts)
+        parts.push({ type: 'reasoning', text: thought.content })
+      const text = textOf(message.content)
+      if (text !== '') parts.push({ type: 'text', text })
+      const calls = message.toolCalls ?? []
+      for (const call of calls) {
+        parts.push({
+          type: 'tool-call',
+          id: call.id,
+          name: call.function.name,
+          argsText: call.function.arguments,
+          args: parseJson(call.function.arguments),
+          status: 'running',
+        })
+      }
+      const media = mediaOfMessage(message)
+      for (const record of media) parts.push(mediaView(record))
+      result.push({ id, role: 'assistant', parts })
+      return
+    }
+    // A tool message holds the result of an earlier tool call. The list is
+    // new here, so it is safe to change in place.
+    const call = findToolCall(result, message.toolCallId)
+    if (!call) return
+    call.status = message.error ? 'failed' : 'done'
+    call.result = parseJson(textOf(message.content))
+    // An agent tool result names its child run. The view loads the child's
+    // own messages into this part.
+    const outcome = recordOf(call.result)
+    const child = outcome.subagentRunId
+    if (typeof child !== 'string' || child === '') return
+    const owner = result.find(
+      (item) => item.role === 'assistant' && item.parts.includes(call),
+    )
+    if (owner?.role !== 'assistant') return
+    const error = outcome.error
+    // A background child answers at once with `status: 'started'`.
+    const isStarted = recordOf(outcome.result).status === 'started'
+    const ended =
+      error === undefined && call.status === 'done' ? 'done' : 'failed'
+    const agent: AgentPart = {
+      type: 'agent',
+      id: child,
+      name: call.name,
+      status: isStarted ? 'running' : ended,
+      ...(typeof error === 'string' ? { error } : {}),
+      parts: [],
+    }
+    owner.parts.splice(owner.parts.indexOf(call) + 1, 0, agent)
+  })
+  return result
+}
+
+/** The parts of a child agent from its saved messages. Its task does not show. */
+export function agentPartsFrom(
+  messages: ReadonlyArray<ModelMessage>,
+): Array<ViewPart> {
+  return messagesFromTranscript(messages).flatMap((message) =>
+    message.role === 'assistant' ? message.parts : [],
+  )
+}
+
+/** The agent parts that show no parts yet. */
+function emptyAgents(parts: ReadonlyArray<ViewPart>): Array<AgentPart> {
+  return parts.flatMap((part) => {
+    if (part.type !== 'agent') return []
+    return part.parts.length === 0 ? [part] : emptyAgents(part.parts)
+  })
+}
+
+/** `emptyAgents` of every assistant message. */
+export function emptyAgentsIn(
+  messages: ReadonlyArray<ViewMessage>,
+): Array<AgentPart> {
+  return messages.flatMap((message) =>
+    message.role === 'assistant' ? emptyAgents(message.parts) : [],
+  )
+}
+
+/**
+ * Put `parts` first in the agent part `id`, in whichever message holds it.
+ * `ended` is how the saved child ended. It changes a part that shows the
+ * child as running, from a background start.
+ */
+export function withAgentParts(
+  state: SessionViewState,
+  id: string,
+  parts: Array<ViewPart>,
+  ended?: AgentPart['status'],
+): SessionViewState {
+  const messages = keep(
+    state.messages,
+    state.messages.map((message) => {
+      if (message.role !== 'assistant') return message
+      // Events can come before the saved messages load. They come after them.
+      const next = mapAgent(message.parts, id, (agent) => {
+        const status =
+          agent.status === 'running' && ended ? ended : agent.status
+        if (parts.length === 0 && status === agent.status) return agent
+        return { ...agent, status, parts: [...parts, ...agent.parts] }
+      })
+      return next === message.parts ? message : { ...message, parts: next }
+    }),
+  )
+  return messages === state.messages ? state : { ...state, messages }
+}
+
+/**
+ * The message, tool call, and child run ids of a saved transcript. A segment
+ * of a message (`<id>-segment-<n>`) has the id of its stream message.
+ */
+export function transcriptIds(
+  messages: ReadonlyArray<ModelMessage>,
+): Set<string> {
+  const ids = new Set<string>()
+  for (const message of messages) {
+    if (message.id) ids.add(message.id.replace(/-segment-\d+$/, ''))
+    for (const call of message.toolCalls ?? []) ids.add(call.id)
+    // The child run an agent tool result names: its parts load on their own.
+    if (message.role !== 'tool') continue
+    const child = recordOf(parseJson(textOf(message.content))).subagentRunId
+    if (typeof child === 'string' && child !== '') ids.add(child)
+  }
+  return ids
+}
diff --git a/packages/ai-harness/src/view/types.ts b/packages/ai-harness/src/view/types.ts
new file mode 100644
index 0000000000..a3deda362a
--- /dev/null
+++ b/packages/ai-harness/src/view/types.ts
@@ -0,0 +1,216 @@
+import type { ConfigOption } from '../config'
+import type { SessionUsage } from '../usage'
+import type {
+  MediaKind,
+  Receipt,
+  ThreadSettings,
+  UserInput,
+  WaitingInput,
+} from '../types'
+
+export type ToolCallStatus = 'running' | 'done' | 'failed' | 'needs-approval'
+
+export interface ToolCallPart {
+  type: 'tool-call'
+  id: string
+  name: string
+  /** The raw JSON arguments as they stream. */
+  argsText: string
+  /** The parsed arguments, after the call ends. */
+  args: unknown
+  status: ToolCallStatus
+  result?: unknown
+}
+
+/** A child agent, with its own text and tool calls. */
+export interface AgentPart {
+  type: 'agent'
+  id: string
+  name: string
+  status: 'running' | 'done' | 'failed'
+  error?: string
+  /** The typed result of the agent, when it gave one. */
+  result?: unknown
+  parts: Array<ViewPart>
+}
+
+/** A media file that the user sent or that an agent made. */
+export interface MediaPart {
+  type: 'media'
+  id: string
+  kind: MediaKind
+  mimeType: string
+  name: string
+  /** Size in bytes. */
+  size: number
+  /**
+   * A URL for `<img>`, `<audio>`, or `<video>`, when the source gives one.
+   * The view gets a new one before it expires.
+   */
+  url?: string
+  /** Read the bytes. Rejects when the source cannot load media. */
+  load: () => Promise<Uint8Array>
+}
+
+export type ViewPart =
+  | { type: 'text'; text: string }
+  | { type: 'reasoning'; text: string }
+  | ToolCallPart
+  | AgentPart
+  | MediaPart
+
+/** Why a notice line is there. */
+export type NoticeKind = 'info' | 'error' | 'rejected' | 'command' | 'ui'
+
+export type ViewMessage =
+  | {
+      id: string
+      role: 'user'
+      text: string
+      /** The files the user sent, when there are any. */
+      media?: Array<MediaPart>
+    }
+  | { id: string; role: 'assistant'; parts: Array<ViewPart> }
+  | { id: string; role: 'notice'; kind: NoticeKind; text: string }
+
+/** What an approval sends with a yes: changed arguments, or data for the tool. */
+export interface ApproveOptions {
+  /** The arguments the tool runs with, in place of the model's. */
+  editedArgs?: unknown
+  payload?: unknown
+}
+
+/** A tool call that waits for a yes or no. */
+export interface Approval {
+  id: string
+  toolCallId?: string
+  tool: string
+  args: unknown
+  message?: string
+  approve: (options?: ApproveOptions) => void
+  /** Say no. `payload` goes to the tool's approval schema, when it has one. */
+  reject: (payload?: unknown) => void
+}
+
+/**
+ * An interrupt that waits for an answer of its own shape, for example an MCP
+ * server that asks for input. The turn waits for it.
+ */
+export interface ViewInterrupt {
+  id: string
+  reason: string
+  message?: string
+  toolCallId?: string
+  /** The child agent that stopped, when a child did. */
+  subagentRunId?: string
+  /** The answer's JSON Schema, when the interrupt has one. */
+  responseSchema?: unknown
+  /** The data the interrupt sent for the UI, when it has some. */
+  payload?: unknown
+  /** Send the answer. */
+  resolve: (value: unknown) => void
+  /** Answer with no value. The turn continues without one. */
+  cancel: () => void
+}
+
+/**
+ * A client tool call: a tool with no server implementation. The UI runs the
+ * tool and sends its output. The turn waits for it.
+ */
+export interface ClientToolCall {
+  id: string
+  toolCallId?: string
+  tool: string
+  args: unknown
+  /** Send the tool's output. */
+  resolve: (output: unknown) => void
+  /** Send a failure. The model sees that the tool failed with `message`. */
+  fail: (message: string) => void
+}
+
+/** A question from a command or a plugin. */
+export interface ViewQuestion {
+  id: string
+  message: string
+  /** The answer's JSON Schema, when the question has one. */
+  schema?: unknown
+  /** The answer is a secret (a key or a password). Do not show what the user types. */
+  secret?: boolean
+  /** A page the user must open before they answer. Show the link. */
+  url?: string
+  answer: (value: unknown) => Promise<Receipt>
+}
+
+/** A connector that needs a sign-in. */
+export interface SignIn {
+  connector: string
+  url?: string
+  userCode?: string
+}
+
+export interface ViewCommand {
+  name: string
+  description: string
+  owner: string
+  /** The input as JSON Schema, when the command has one. */
+  input?: unknown
+}
+
+export interface ViewConfigEntry {
+  key: string
+  owner: string
+  value: unknown
+  option: ConfigOption
+}
+
+/** A background agent that runs now. */
+export interface ViewAgent {
+  id: string
+  name: string
+  /**
+   * Send a message to this run. `mode` is `'steer'` (default) or
+   * `'followUp'`, as in `AgentRun.send`. Rejects when the view's source
+   * cannot send messages to agents.
+   */
+  send: (
+    message: UserInput,
+    options?: { mode?: 'steer' | 'followUp' },
+  ) => Promise<Receipt>
+  /** Stop this run, and the runs it started. */
+  cancel: () => Promise<Receipt>
+}
+
+/**
+ * Everything a UI can show about a session.
+ *
+ * @experimental The fields can change in a minor release.
+ */
+export interface SessionViewState {
+  threadId: string
+  status: 'idle' | 'running' | 'requires_action'
+  connection: 'open' | 'reconnecting' | 'closed'
+  messages: Array<ViewMessage>
+  approvals: Array<Approval>
+  /** Client tool calls that wait for their output from the UI. */
+  clientTools: Array<ClientToolCall>
+  /** Other interrupts that wait for an answer. */
+  interrupts: Array<ViewInterrupt>
+  questions: Array<ViewQuestion>
+  signIns: Array<SignIn>
+  /** Background agents that run now. */
+  agents: Array<ViewAgent>
+  queuedTurns: number
+  /** The inputs that wait, in the order they run. */
+  waitingInputs: Array<WaitingInput>
+  commands: Array<ViewCommand>
+  config: Array<ViewConfigEntry>
+  tools: Array<{ name: string; owner: string }>
+  /** The names of `defineHarness({ models })`, for a model menu. */
+  models: Array<string>
+  /** The stored settings of the thread, from `configure`. */
+  settings?: ThreadSettings
+  /** The token usage of the thread. */
+  usage?: SessionUsage
+  /** Each plugin's saved state, by plugin name. */
+  plugins: Record<string, unknown>
+}
diff --git a/packages/ai-harness/tests/auth-wait.test.ts b/packages/ai-harness/tests/auth-wait.test.ts
new file mode 100644
index 0000000000..5750f650e0
--- /dev/null
+++ b/packages/ai-harness/tests/auth-wait.test.ts
@@ -0,0 +1,534 @@
+import { describe, expect, it } from 'vitest'
+import { toolDefinition } from '@tanstack/ai'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  AuthRequiredError,
+  HARNESS_EVENTS,
+  createHarnessHandler,
+  createHarnessHost,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+  oauthConnector,
+} from '../src'
+import { after, gate, mockAdapter, text, toolCall } from './helpers'
+import type { HarnessSession, OAuthConfig } from '../src'
+import type { Reply } from './helpers'
+
+const oauth: OAuthConfig = {
+  authorizationUrl: 'https://auth.example/authorize',
+  tokenUrl: 'https://auth.example/token',
+  deviceUrl: 'https://auth.example/device',
+  clientId: 'client-1',
+  scopes: ['repo'],
+}
+
+/**
+ * A `github` tool that needs a credential, and a `connect:github` command
+ * that saves one. `wait` is the option the tool gives `require`.
+ */
+function github(seen: Array<string>, wait: boolean) {
+  return definePlugin({
+    name: 'test/github',
+    setup: (ctx) => ({
+      tools: [
+        toolDefinition({
+          name: 'list_issues',
+          description: 'List issues',
+        }).server(async () => {
+          const credential = await ctx.credentials.require(
+            'github',
+            wait ? { wait: true } : undefined,
+          )
+          seen.push(credential.type === 'api_key' ? credential.value : '')
+          return ['#1']
+        }),
+      ],
+      commands: {
+        // A command saves for the user who runs it.
+        'connect:github': defineCommand({
+          description: 'Sign in to GitHub',
+          run: async (_input, command) => {
+            await command.credentials.set({
+              id: 'github',
+              credential: {
+                type: 'api_key',
+                value: `${command.principal?.id}-key`,
+              },
+            })
+            return 'Connected.'
+          },
+        }),
+        // A save of another credential, by the session's own access.
+        note: defineCommand({
+          description: 'Save a note credential',
+          run: () =>
+            ctx.credentials.set({
+              id: 'note',
+              credential: { type: 'api_key', value: 'n' },
+            }),
+        }),
+      },
+    }),
+  })
+}
+
+/** The next settlement that is not `interrupted`. Start it before the input. */
+function nextEnd(session: HarnessSession) {
+  return (async () => {
+    for await (const { event } of session.events({
+      from: session.snapshot().cursor,
+    })) {
+      if (event.type !== 'CUSTOM' || event.name !== HARNESS_EVENTS.inputSettled)
+        continue
+      const value = event.value as { outcome: string }
+      if (value.outcome !== 'interrupted') return value
+    }
+    throw new Error('The session closed.')
+  })()
+}
+
+/** The stores of a durable host, so a second host reads the same thread. */
+function durableStores() {
+  const { runs, metadata, credentials } = memoryPersistence().stores
+  return { log: memoryLogStore(), runs, metadata, credentials }
+}
+
+describe('require with wait', () => {
+  it('stops the turn for the sign-in, and connect runs the tool again', async () => {
+    const seenTokens: Array<string> = []
+    const responses: Array<Record<string, unknown>> = [
+      {
+        device_code: 'd1',
+        user_code: 'WXYZ',
+        verification_uri: 'https://gh.example/device',
+        interval: 1,
+      },
+      { access_token: 'gh-token' },
+    ]
+    const fake: typeof fetch = async () =>
+      new Response(JSON.stringify(responses.shift()), {
+        headers: { 'content-type': 'application/json' },
+      })
+    const connector = oauthConnector({
+      id: 'github',
+      label: 'GitHub',
+      oauth,
+      login: 'device',
+      fetch: fake,
+      tools: (token) => [
+        toolDefinition({
+          name: 'list_issues',
+          description: 'List issues',
+        }).server(async () => {
+          seenTokens.push(await token({ wait: true }))
+          return ['#1']
+        }),
+      ],
+    })
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('list_issues', {}),
+      () => text('One issue.'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/auth-wait',
+        adapter,
+        plugins: () => [connector],
+      }),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+    const signIns: Array<unknown> = []
+    const reader = new AbortController()
+    void (async () => {
+      for await (const { event } of session.events({
+        signal: reader.signal,
+      })) {
+        if (
+          event.type === 'CUSTOM' &&
+          event.name === HARNESS_EVENTS.authRequired
+        )
+          signIns.push(event.value)
+      }
+    })()
+
+    const turn = await session.prompt('List my issues.', { inputId: 'ask' })
+    expect(turn.interrupts).toMatchObject([
+      {
+        reason: 'auth_required',
+        toolCallId: 'call-1',
+        metadata: {
+          'tanstack:interruptPayload': { request: { connector: 'github' } },
+        },
+      },
+    ])
+    expect(await session.settled('ask')).toMatchObject({
+      outcome: 'interrupted',
+    })
+    expect(signIns).toEqual([{ connector: 'github' }])
+    expect(seenTokens).toEqual([])
+
+    const ended = nextEnd(session)
+    await expect(session.command('connect:github')).resolves.toBe(
+      'Connected to GitHub.',
+    )
+    expect(await ended).toMatchObject({ outcome: 'completed' })
+    expect(seenTokens).toEqual(['gh-token'])
+    // No new prompt: the second model call is the answer of the same turn.
+    expect(calls).toHaveLength(2)
+    expect(session.snapshot().pendingInterrupts).toEqual([])
+    reader.abort()
+    await host.close()
+  })
+
+  it('continues the turn on another host after a restart', async () => {
+    const stores = durableStores()
+    const seen: Array<string> = []
+    const start = (replies: Array<Reply>) => {
+      const { adapter } = mockAdapter(replies)
+      const host = createHarnessHost({ persistence: { stores } })
+      const harness = defineHarness({
+        name: 'test/auth-wait-restart',
+        adapter,
+        plugins: () => [github(seen, true)],
+      })
+      return {
+        host,
+        open: () =>
+          host.open(harness, { threadId: 't', principal: { id: 'user-1' } }),
+      }
+    }
+
+    const a = start([() => toolCall('list_issues', {})])
+    const turn = await (await a.open()).prompt('List my issues.')
+    expect(turn.interrupts?.[0]?.reason).toBe('auth_required')
+    await a.host.close()
+
+    const b = start([() => text('One issue.')])
+    const session = await b.open()
+    expect(session.snapshot().pendingInterrupts).toMatchObject([
+      { reason: 'auth_required' },
+    ])
+    const ended = nextEnd(session)
+    await session.command('connect:github')
+    expect(await ended).toMatchObject({ outcome: 'completed' })
+    expect(seen).toEqual(['user-1-key'])
+    await b.host.close()
+  })
+
+  it('fails the tool as before when the user cancels the sign-in', async () => {
+    const seen: Array<string> = []
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('list_issues', {}),
+      () => text('You did not sign in.'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/auth-wait-cancel',
+        adapter,
+        plugins: () => [github(seen, true)],
+      }),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+    const turn = await session.prompt('List my issues.')
+    const interruptId = turn.interrupts?.[0]?.id
+    if (!interruptId) throw new Error('The turn did not stop for the sign-in.')
+
+    const receipt = await session.resolve(
+      [{ interruptId, status: 'cancelled' }],
+      { inputId: 'no' },
+    )
+    expect(receipt.status).toBe('accepted')
+    expect(await session.settled('no')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(seen).toEqual([])
+    expect(session.snapshot().pendingInterrupts).toEqual([])
+    // The model got the tool error, as without `wait`.
+    expect(JSON.stringify(calls[1]?.messages)).toContain(
+      'Sign in to github first',
+    )
+    await host.close()
+  })
+
+  it('fails the tool without wait, as before', async () => {
+    const seen: Array<string> = []
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('list_issues', {}),
+      () => text('Sign in first.'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/auth-no-wait',
+        adapter,
+        plugins: () => [github(seen, false)],
+      }),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+    const turn = await session.prompt('List my issues.', { inputId: 'ask' })
+    expect(turn.interrupts).toBeUndefined()
+    expect(await session.settled('ask')).toMatchObject({
+      outcome: 'completed',
+    })
+    expect(JSON.stringify(calls[1]?.messages)).toContain(
+      'Sign in to github first',
+    )
+
+    // A credential saved later starts nothing.
+    await session.command('connect:github')
+    expect(calls).toHaveLength(2)
+    expect(seen).toEqual([])
+    await host.close()
+  })
+
+  it('does not wait in a command, also while a turn runs', async () => {
+    const started = gate()
+    const release = gate()
+    const { adapter } = mockAdapter([
+      (request) => (started.open(), after(release.opened, 'Done.')(request)),
+    ])
+    const caught: Array<unknown> = []
+    const checker = definePlugin({
+      name: 'test/checker',
+      setup: () => ({
+        commands: {
+          check: defineCommand({
+            description: 'Check the GitHub sign-in',
+            run: async (_input, { credentials }) => {
+              await credentials
+                .require('github', { wait: true })
+                .catch((error: unknown) => caught.push(error))
+            },
+          }),
+        },
+      }),
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/auth-command-wait',
+        adapter,
+        plugins: () => [checker],
+      }),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+    const turn = session.prompt('Work.')
+    await started.opened
+    await session.command('check')
+    release.open()
+    await turn
+
+    expect(caught).toHaveLength(1)
+    expect(caught[0]).toBeInstanceOf(AuthRequiredError)
+    await host.close()
+  })
+})
+
+describe('sign-ins in a shared thread', () => {
+  const alice = { id: 'alice' }
+  const bob = { id: 'bob' }
+
+  it("never answers bob's sign-in with alice's credential", async () => {
+    const seen: Array<string> = []
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('list_issues', {}),
+      () => text('One issue.'),
+    ])
+    const persistence = memoryPersistence()
+    await persistence.stores.credentials.set({
+      scope: { threadId: 't', userId: 'alice' },
+      id: 'github',
+      credential: { type: 'api_key', value: 'alice-key' },
+    })
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/auth-wait-shared',
+        adapter,
+        plugins: () => [github(seen, true)],
+      }),
+      { threadId: 't', principal: alice },
+    )
+    const turn = await session.prompt('List my issues.', { principal: bob })
+    expect(turn.interrupts?.[0]?.reason).toBe('auth_required')
+
+    // Saves for alice, while bob's turn waits for bob's sign-in.
+    await session.command('note')
+    expect(session.snapshot().pendingInterrupts).toHaveLength(1)
+    await session.command('connect:github', undefined, { principal: alice })
+
+    expect(seen).toEqual([])
+    expect(calls).toHaveLength(1)
+    expect(session.snapshot().pendingInterrupts).toMatchObject([
+      { reason: 'auth_required' },
+    ])
+    await host.close()
+  })
+
+  it("saves bob's sign-in for bob and continues bob's turn as bob", async () => {
+    const seen: Array<string> = []
+    const { adapter, calls } = mockAdapter([
+      () => toolCall('list_issues', {}),
+      () => text('One issue.'),
+    ])
+    const persistence = memoryPersistence()
+    const host = createHarnessHost({ persistence })
+    const harness = defineHarness({
+      name: 'test/auth-wait-shared-http',
+      adapter,
+      plugins: () => [github(seen, true)],
+      expose: { commands: ['connect:github'] },
+    })
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      canAccess: () => true,
+      authorize: (request) => ({ id: request.headers.get('x-user') ?? '' }),
+    })
+    const control = async (user: string, input: object) =>
+      (
+        await handler(
+          new Request('http://h.test/control', {
+            method: 'POST',
+            headers: { 'x-user': user },
+            body: JSON.stringify({ threadId: 't', input }),
+          }),
+        )
+      ).json()
+    // Alice opens the thread. Bob's turn waits for bob's sign-in.
+    const session = await host.open(harness, {
+      threadId: 't',
+      principal: alice,
+    })
+    const asked = await control('bob', {
+      op: 'prompt',
+      message: 'List my issues.',
+    })
+    expect(await session.settled(asked.inputId)).toMatchObject({
+      outcome: 'interrupted',
+    })
+
+    const ended = nextEnd(session)
+    await control('bob', { op: 'command', name: 'connect:github' })
+    expect(await ended).toMatchObject({ outcome: 'completed' })
+    expect(seen).toEqual(['bob-key'])
+    expect(calls).toHaveLength(2)
+    const { credentials } = persistence.stores
+    expect(
+      await credentials.get({
+        scope: { threadId: 't', userId: 'bob' },
+        id: 'github',
+      }),
+    ).toMatchObject({ value: 'bob-key' })
+    expect(
+      await credentials.get({
+        scope: { threadId: 't', userId: 'alice' },
+        id: 'github',
+      }),
+    ).toBeNull()
+    await host.close()
+  })
+
+  it('runs a command from control as its sender, and the log keeps the sender', async () => {
+    const ran: Array<string | undefined> = []
+    const stores = durableStores()
+    const host = createHarnessHost({ persistence: { stores } })
+    const harness = defineHarness({
+      name: 'test/command-sender',
+      adapter: mockAdapter([]).adapter,
+      plugins: () => [
+        definePlugin({
+          name: 'test/whoami',
+          setup: () => ({
+            commands: {
+              whoami: defineCommand({
+                description: 'Who runs this?',
+                run: (_input, command) => {
+                  ran.push(command.principal?.id)
+                  return command.principal?.id
+                },
+              }),
+            },
+          }),
+        }),
+      ],
+      expose: { commands: ['whoami'] },
+    })
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      canAccess: () => true,
+      authorize: () => bob,
+      mediaSecret: 'test-secret',
+    })
+    const session = await host.open(harness, {
+      threadId: 't',
+      principal: alice,
+    })
+    const receipt = await (
+      await handler(
+        new Request('http://h.test/control', {
+          method: 'POST',
+          body: JSON.stringify({
+            threadId: 't',
+            input: { op: 'command', name: 'whoami' },
+          }),
+        }),
+      )
+    ).json()
+    await expect(session.operation(receipt.operationId)).resolves.toBe('bob')
+    expect(ran).toEqual(['bob'])
+    const commands = (await stores.log.read('t'))
+      .map((entry) => entry.record)
+      .filter(
+        (record) =>
+          record.type === 'harness.input' &&
+          (record['input'] as { op?: string } | undefined)?.op === 'command',
+      )
+    expect(commands.map((record) => record['principal'])).toEqual([
+      { id: 'bob' },
+    ])
+    await host.close()
+  })
+
+  it('loads a stored sign-in wait from before senders were kept', async () => {
+    const stores = durableStores()
+    const seen: Array<string> = []
+    const start = (replies: Array<Reply>) => {
+      const { adapter } = mockAdapter(replies)
+      const host = createHarnessHost({ persistence: { stores } })
+      const harness = defineHarness({
+        name: 'test/auth-wait-old-copy',
+        adapter,
+        plugins: () => [github(seen, true)],
+      })
+      return {
+        host,
+        open: () => host.open(harness, { threadId: 't', principal: alice }),
+      }
+    }
+    const a = start([() => toolCall('list_issues', {})])
+    await (await a.open()).prompt('List my issues.')
+    await a.host.close()
+    // A copy without `principal`, as an older version wrote it.
+    const stored = await stores.metadata.get('harness:interrupted', 't')
+    if (typeof stored !== 'object' || stored === null)
+      throw new Error('No stored interrupted turn.')
+    const { principal: _principal, ...old } = stored as Record<string, unknown>
+    await stores.metadata.set('harness:interrupted', 't', old)
+
+    const b = start([() => text('One issue.')])
+    const session = await b.open()
+    expect(session.snapshot().pendingInterrupts).toMatchObject([
+      { reason: 'auth_required' },
+    ])
+    const ended = nextEnd(session)
+    await session.command('connect:github')
+    expect(await ended).toMatchObject({ outcome: 'completed' })
+    expect(seen).toEqual(['alice-key'])
+    await b.host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/auth.test.ts b/packages/ai-harness/tests/auth.test.ts
index 46cd5943be..5d9e2863c5 100644
--- a/packages/ai-harness/tests/auth.test.ts
+++ b/packages/ai-harness/tests/auth.test.ts
@@ -1,14 +1,270 @@
-import { describe, expect, it } from 'vitest'
-import { EventType, defineAgent } from '@tanstack/ai'
+import { describe, expect, it, vi } from 'vitest'
+import { EventType, defineAgent, toolDefinition } from '@tanstack/ai'
 import { memoryPersistence } from '@tanstack/ai-persistence'
 import {
+  HARNESS_EVENTS,
+  buildAuthorizationUrl,
   createHarnessHost,
+  createPkce,
   defineCommand,
   defineHarness,
   definePlugin,
+  deviceLogin,
+  exchangeCode,
+  loopbackLogin,
+  oauthConnector,
+  refreshCredential,
   scrubSecrets,
 } from '../src'
-import { mockAdapter, text } from './helpers'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { OAuthConfig, SessionEvent } from '../src'
+
+const oauth: OAuthConfig = {
+  authorizationUrl: 'https://auth.example/authorize',
+  tokenUrl: 'https://auth.example/token',
+  deviceUrl: 'https://auth.example/device',
+  clientId: 'client-1',
+  scopes: ['repo', 'read:user'],
+}
+
+/** A fake token endpoint that records each form body. */
+function tokenEndpoint(responses: Array<Record<string, unknown>>) {
+  const bodies: Array<URLSearchParams> = []
+  const fake: typeof fetch = async (_input, init) => {
+    bodies.push(new URLSearchParams(String(init?.body)))
+    return new Response(JSON.stringify(responses.shift() ?? {}), {
+      headers: { 'content-type': 'application/json' },
+    })
+  }
+  return { fake, bodies }
+}
+
+describe('PKCE and URLs', () => {
+  it('makes an S256 challenge from the verifier', async () => {
+    const { verifier, challenge } = await createPkce()
+    const digest = await crypto.subtle.digest(
+      'SHA-256',
+      new TextEncoder().encode(verifier),
+    )
+    const expected = Buffer.from(digest).toString('base64url')
+    expect(challenge).toBe(expected)
+    expect(verifier.length).toBeGreaterThanOrEqual(43)
+  })
+
+  it('builds the authorization URL with state, PKCE, and scopes', () => {
+    const url = new URL(
+      buildAuthorizationUrl(oauth, {
+        redirectUri: 'http://127.0.0.1:5000/callback',
+        state: 's1',
+        challenge: 'c1',
+      }),
+    )
+    expect(url.searchParams.get('client_id')).toBe('client-1')
+    expect(url.searchParams.get('code_challenge_method')).toBe('S256')
+    expect(url.searchParams.get('scope')).toBe('repo read:user')
+    expect(url.searchParams.get('state')).toBe('s1')
+  })
+})
+
+describe('token exchange', () => {
+  it('trades a code for tokens and refreshes them', async () => {
+    const { fake, bodies } = tokenEndpoint([
+      {
+        access_token: 'a1',
+        refresh_token: 'r1',
+        expires_in: 3600,
+        scope: 'repo',
+      },
+      { access_token: 'a2', expires_in: 3600 },
+    ])
+    const first = await exchangeCode(oauth, {
+      code: 'code-1',
+      verifier: 'v1',
+      redirectUri: 'http://127.0.0.1/callback',
+      fetch: fake,
+    })
+    expect(first).toMatchObject({
+      type: 'oauth',
+      accessToken: 'a1',
+      refreshToken: 'r1',
+      scopes: ['repo'],
+    })
+    expect(bodies[0]?.get('code_verifier')).toBe('v1')
+
+    const refreshed = await refreshCredential(oauth, first, fake)
+    // The old refresh token stays when the server sends no new one.
+    expect(refreshed).toMatchObject({ accessToken: 'a2', refreshToken: 'r1' })
+    expect(bodies[1]?.get('grant_type')).toBe('refresh_token')
+  })
+
+  it('reports an OAuth error', async () => {
+    const { fake } = tokenEndpoint([{ error: 'bad_verification_code' }])
+    await expect(
+      exchangeCode(oauth, {
+        code: 'x',
+        verifier: 'y',
+        redirectUri: 'z',
+        fetch: fake,
+      }),
+    ).rejects.toThrow('bad_verification_code')
+  })
+})
+
+describe('loopback login', () => {
+  it('receives the code on 127.0.0.1 and rejects a wrong state', async () => {
+    const { fake } = tokenEndpoint([{ access_token: 'loop-token' }])
+    const signedIn = loopbackLogin(oauth, {
+      fetch: fake,
+      onUrl: (url) => {
+        const parsed = new URL(url)
+        const redirect = new URL(parsed.searchParams.get('redirect_uri')!)
+        expect(redirect.hostname).toBe('127.0.0.1')
+        redirect.searchParams.set('code', 'the-code')
+        redirect.searchParams.set('state', parsed.searchParams.get('state')!)
+        void fetch(redirect)
+      },
+    })
+    await expect(signedIn).resolves.toMatchObject({ accessToken: 'loop-token' })
+
+    const forged = loopbackLogin(oauth, {
+      fetch: fake,
+      onUrl: (url) => {
+        const redirect = new URL(new URL(url).searchParams.get('redirect_uri')!)
+        redirect.searchParams.set('code', 'x')
+        redirect.searchParams.set('state', 'forged')
+        void fetch(redirect)
+      },
+    })
+    await expect(forged).rejects.toThrow('state does not match')
+  })
+})
+
+describe('device login', () => {
+  it('shows the code and polls until the user approves', async () => {
+    const responses: Array<Record<string, unknown>> = [
+      {
+        device_code: 'd1',
+        user_code: 'ABCD-1234',
+        verification_uri: 'https://auth.example/device',
+        interval: 1,
+      },
+      { error: 'authorization_pending' },
+      { access_token: 'device-token' },
+    ]
+    const fake: typeof fetch = async () =>
+      new Response(JSON.stringify(responses.shift()), {
+        headers: { 'content-type': 'application/json' },
+      })
+    const onCode = vi.fn()
+    const credential = await deviceLogin(oauth, {
+      fetch: fake,
+      onCode,
+      sleep: async () => {},
+    })
+    expect(onCode).toHaveBeenCalledWith({
+      userCode: 'ABCD-1234',
+      verificationUri: 'https://auth.example/device',
+    })
+    expect(credential).toMatchObject({ accessToken: 'device-token' })
+  })
+})
+
+describe('oauthConnector', () => {
+  it('asks for sign-in, connects, and gives tools a token', async () => {
+    const seenTokens: Array<string> = []
+    const responses: Array<Record<string, unknown>> = [
+      {
+        device_code: 'd1',
+        user_code: 'WXYZ',
+        verification_uri: 'https://gh.example/device',
+        interval: 1,
+      },
+      { access_token: 'gh-token' },
+    ]
+    const fake: typeof fetch = async () =>
+      new Response(JSON.stringify(responses.shift()), {
+        headers: { 'content-type': 'application/json' },
+      })
+    const github = oauthConnector({
+      id: 'github',
+      label: 'GitHub',
+      oauth,
+      login: 'device',
+      fetch: fake,
+      tools: (token) => [
+        toolDefinition({
+          name: 'list_issues',
+          description: 'List issues',
+        }).server(async () => {
+          seenTokens.push(await token())
+          return ['#1']
+        }),
+      ],
+    })
+    const persistence = memoryPersistence()
+    const { adapter } = mockAdapter([
+      () => toolCall('list_issues', {}),
+      () => text('Sign in first.'),
+      () => toolCall('list_issues', {}),
+      () => text('One issue.'),
+    ])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/connector',
+        adapter,
+        plugins: () => [github],
+      }),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+    const events: Array<SessionEvent> = []
+    const reader = new AbortController()
+    const reading = (async () => {
+      for await (const entry of session.events({ signal: reader.signal }))
+        events.push(entry)
+    })()
+
+    // Before sign-in, the tool asks for it.
+    await session.prompt('list my issues')
+    expect(seenTokens).toEqual([])
+    expect(
+      events.some(
+        (entry) =>
+          entry.event.type === 'CUSTOM' &&
+          entry.event.name === HARNESS_EVENTS.authRequired &&
+          (entry.event.value as { connector: string }).connector === 'github',
+      ),
+    ).toBe(true)
+
+    await expect(session.command('connect:github')).resolves.toBe(
+      'Connected to GitHub.',
+    )
+    const saved = await persistence.stores.credentials.get({
+      scope: { threadId: 't', userId: 'user-1' },
+      id: 'github',
+    })
+    expect(saved).toMatchObject({ accessToken: 'gh-token' })
+
+    await session.prompt('list my issues again')
+    expect(seenTokens).toEqual(['gh-token'])
+    // The model never sees the token.
+    const transcript = JSON.stringify(
+      await persistence.stores.messages.loadThread('t'),
+    )
+    expect(transcript).not.toContain('gh-token')
+
+    await session.command('disconnect:github')
+    expect(
+      await persistence.stores.credentials.list({
+        threadId: 't',
+        userId: 'user-1',
+      }),
+    ).toEqual([])
+    reader.abort()
+    await reading
+    await host.close()
+  })
+})
 
 describe('scrubSecrets', () => {
   it('removes known secrets from text', () => {
diff --git a/packages/ai-harness/tests/client-media.test.ts b/packages/ai-harness/tests/client-media.test.ts
new file mode 100644
index 0000000000..09cbaf46b6
--- /dev/null
+++ b/packages/ai-harness/tests/client-media.test.ts
@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest'
+import { createHarnessClient } from '../src/client'
+import type { MediaRecord } from '../src/client'
+
+const record: MediaRecord = {
+  id: 'm1',
+  threadId: 'thread-m',
+  kind: 'image',
+  mimeType: 'image/png',
+  name: 'cat photo.png',
+  size: 3,
+  source: 'user',
+  createdAt: 1,
+}
+
+// A fake handler: it keeps each request and answers with `answer`.
+function setup(answer: (request: Request) => Response) {
+  const requests: Array<Request> = []
+  const client = createHarnessClient({
+    url: 'http://local/api/harness/',
+    threadId: 'thread-m',
+    headers: () => ({ authorization: 'Bearer t' }),
+    fetch: async (input, init) => {
+      const request = new Request(input, init)
+      requests.push(request)
+      return answer(request)
+    },
+  })
+  return { client, requests }
+}
+
+// What the client sent in its first request.
+async function sent(requests: Array<Request>) {
+  const [request] = requests
+  if (!request) throw new Error('The client sent no request')
+  return {
+    url: request.url,
+    method: request.method,
+    contentType: request.headers.get('content-type'),
+    authorization: request.headers.get('authorization'),
+    body: [...new Uint8Array(await request.arrayBuffer())],
+  }
+}
+
+describe('client media', () => {
+  it('uploads the raw bytes with their type and returns the stored record', async () => {
+    const { client, requests } = setup(() => Response.json(record))
+
+    // A view on a bigger buffer: only the bytes of the view are sent.
+    const bytes = new Uint8Array([0, 1, 2, 3, 9]).subarray(1, 4)
+
+    const stored = await client.upload(bytes, {
+      name: 'cat photo.png',
+      mimeType: 'image/png',
+    })
+
+    expect(stored).toEqual(record)
+    expect(await sent(requests)).toEqual({
+      url: 'http://local/api/harness/media?threadId=thread-m&name=cat+photo.png',
+      method: 'POST',
+      contentType: 'image/png',
+      authorization: 'Bearer t',
+      body: [1, 2, 3],
+    })
+  })
+
+  it('throws with the status and the error of a refused upload', async () => {
+    const { client } = setup(() =>
+      Response.json({ error: 'The file is over 100 MB' }, { status: 413 }),
+    )
+
+    await expect(
+      client.upload(new Blob(['big']), {
+        name: 'big.mp4',
+        mimeType: 'video/mp4',
+      }),
+    ).rejects.toThrow('Harness upload failed (413): The file is over 100 MB')
+  })
+
+  it('throws with the status text when a proxy refuses the upload with a page', async () => {
+    const { client } = setup(
+      () =>
+        new Response('<html>Too large</html>', {
+          status: 413,
+          statusText: 'Payload Too Large',
+        }),
+    )
+
+    await expect(
+      client.upload(new ArrayBuffer(3), {
+        name: 'a.png',
+        mimeType: 'image/png',
+      }),
+    ).rejects.toThrow('Harness upload failed (413): Payload Too Large')
+  })
+
+  it('throws a clear error when the upload answer is not a media record', async () => {
+    const { client } = setup(() => Response.json({ id: 'm1' }))
+
+    await expect(
+      client.upload(new Blob(['abc']), {
+        name: 'a.png',
+        mimeType: 'image/png',
+      }),
+    ).rejects.toThrow('Harness upload failed: the answer is not a media record')
+  })
+
+  it('makes the signed path of a media file an absolute url', async () => {
+    const { client, requests } = setup(() =>
+      Response.json({
+        path: 'media?threadId=thread-m&id=m1&exp=5000&sig=abc',
+        expiresAt: 5000,
+      }),
+    )
+
+    expect(await client.mediaUrl('m1')).toEqual({
+      url: 'http://local/api/harness/media?threadId=thread-m&id=m1&exp=5000&sig=abc',
+      expiresAt: 5000,
+    })
+    expect(await sent(requests)).toEqual({
+      url: 'http://local/api/harness/media-url?threadId=thread-m&id=m1',
+      method: 'GET',
+      contentType: null,
+      authorization: 'Bearer t',
+      body: [],
+    })
+  })
+
+  it('throws when the media-url answer has no signed path', async () => {
+    const { client } = setup(() => Response.json({ expiresAt: 5000 }))
+
+    await expect(client.mediaUrl('m1')).rejects.toThrow(
+      'Harness media-url failed: the answer has no signed path',
+    )
+  })
+
+  it('loads the bytes of a media file', async () => {
+    const { client, requests } = setup(
+      () => new Response(new Uint8Array([7, 8, 9])),
+    )
+
+    expect([...(await client.loadMedia('m1'))]).toEqual([7, 8, 9])
+    expect(await sent(requests)).toEqual({
+      url: 'http://local/api/harness/media?threadId=thread-m&id=m1',
+      method: 'GET',
+      contentType: null,
+      authorization: 'Bearer t',
+      body: [],
+    })
+  })
+
+  it('throws instead of returning the error page of a missing media file', async () => {
+    const { client } = setup(() => new Response('not found', { status: 404 }))
+
+    await expect(client.loadMedia('gone')).rejects.toThrow(
+      'Harness media failed (404)',
+    )
+  })
+})
diff --git a/packages/ai-harness/tests/client-reads.test.ts b/packages/ai-harness/tests/client-reads.test.ts
new file mode 100644
index 0000000000..a672a9318c
--- /dev/null
+++ b/packages/ai-harness/tests/client-reads.test.ts
@@ -0,0 +1,236 @@
+import { describe, expect, it, vi } from 'vitest'
+import { defineAgent } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  configOption,
+  createHarnessHandler,
+  createHarnessHost,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import { createHarnessClient } from '../src/client'
+import { mockAdapter, text, toolCall } from './helpers'
+
+const asker = definePlugin({
+  name: 'test/asker',
+  setup: () => ({
+    config: { tone: configOption.text({ default: 'plain' }) },
+    commands: {
+      confirm: defineCommand({
+        description: 'Ask, then answer',
+        run: async (_input, ctx) =>
+          `got ${String(await ctx.session.ask({ message: 'Sure?' }))}`,
+      }),
+    },
+  }),
+})
+
+function setup(
+  fetchWrap?: (fetch: typeof globalThis.fetch) => typeof globalThis.fetch,
+) {
+  const { adapter } = mockAdapter([() => text('hello from the host')])
+  const harness = defineHarness({
+    name: 'test/client-reads',
+    adapter,
+    plugins: () => [asker],
+    expose: { config: ['tone'], commands: ['confirm'] },
+  })
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const handler = createHarnessHandler({
+    host,
+    harness,
+    authorize: () => ({ id: 'u' }),
+    canAccess: (_principal, threadId) => threadId !== 'someone-else',
+  })
+  const direct: typeof globalThis.fetch = (input, init) =>
+    handler(new Request(input, init))
+  const client = createHarnessClient({
+    url: 'http://local/api/harness',
+    threadId: 'thread-r',
+    fetch: fetchWrap ? fetchWrap(direct) : direct,
+    reconnectDelayMs: 1,
+  })
+  return { host, client, handler }
+}
+
+describe('client reads and actions', () => {
+  it('reads the transcript and the description', async () => {
+    const { host, client } = setup()
+    await client.prompt('hi')
+    await vi.waitFor(async () =>
+      expect(JSON.stringify(await client.transcript())).toContain(
+        'hello from the host',
+      ),
+    )
+
+    const description = await client.describe()
+
+    expect(description.commands.map((command) => command.name)).toEqual([
+      'confirm',
+    ])
+    expect(description.config).toEqual([
+      expect.objectContaining({ key: 'tone', value: 'plain' }),
+    ])
+    await host.close()
+  })
+
+  it('runs a command, answers its question, and changes a setting', async () => {
+    const { host, client } = setup()
+
+    expect((await client.command('confirm')).status).toBe('accepted')
+    await vi.waitFor(async () =>
+      expect((await client.snapshot()).pendingQuestions).toHaveLength(1),
+    )
+    const [question] = (await client.snapshot()).pendingQuestions
+    expect(
+      (
+        await client.answer({
+          questionId: question?.questionId ?? '',
+          value: 'yes',
+        })
+      ).status,
+    ).toBe('accepted')
+    await vi.waitFor(async () =>
+      expect((await client.snapshot()).pendingQuestions).toHaveLength(0),
+    )
+
+    expect(
+      (await client.setConfig({ key: 'tone', value: 'warm' })).status,
+    ).toBe('accepted')
+    expect((await client.describe()).config[0]?.value).toBe('warm')
+    await host.close()
+  })
+
+  it('renames, updates, and forks a session of the user', async () => {
+    const { host, client } = setup()
+    await client.prompt('hi')
+    await vi.waitFor(async () =>
+      expect(await client.transcript()).toHaveLength(2),
+    )
+    const [first] = await client.transcript()
+
+    const renamed = await client.renameSession({
+      threadId: 'thread-r',
+      title: 'Greeting',
+    })
+    const pinned = await client.updateSession({
+      threadId: 'thread-r',
+      pinned: true,
+    })
+    const fork = await client.forkSession({
+      threadId: 'thread-r',
+      at: { through: first?.id ?? '' },
+    })
+
+    expect(renamed).toMatchObject({ threadId: 'thread-r', title: 'Greeting' })
+    expect(pinned).toMatchObject({ title: 'Greeting', pinned: true })
+    expect(fork).toMatchObject({ title: 'Greeting (fork)' })
+    expect(fork.threadId).not.toBe('thread-r')
+    await host.close()
+  })
+
+  it('refuses a read without a thread id, or for a thread the user may not open', async () => {
+    const { host, handler } = setup()
+    const statusOf = async (path: string) =>
+      (await handler(new Request(`http://local/api/harness/${path}`))).status
+
+    expect(await statusOf('transcript')).toBe(400)
+    expect(await statusOf('describe')).toBe(400)
+    expect(await statusOf('transcript?threadId=someone-else')).toBe(403)
+    expect(await statusOf('describe?threadId=someone-else')).toBe(403)
+    await host.close()
+  })
+
+  it('reads the transcript of a child agent run', async () => {
+    const writer = defineAgent({
+      name: 'writer',
+      description: 'Writes notes',
+      run: (ctx) =>
+        ctx.chat({ adapter: mockAdapter(() => text('Note 1')).adapter }),
+    })
+    const { adapter } = mockAdapter([
+      () => toolCall('writer', { prompt: 'Take notes' }, 'call-1'),
+      () => text('Done.'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const handler = createHarnessHandler({
+      host,
+      harness: defineHarness({
+        name: 'test/client-reads-agents',
+        adapter,
+        subagents: { agents: [writer] },
+      }),
+      authorize: () => ({ id: 'u' }),
+      canAccess: (_principal, threadId) => threadId !== 'someone-else',
+    })
+    const client = createHarnessClient({
+      url: 'http://local/api/harness',
+      threadId: 'thread-a',
+      fetch: (input, init) => handler(new Request(input, init)),
+    })
+    await client.prompt('Notes, please')
+    const childId = await vi.waitFor(async () => {
+      const result = (await client.transcript()).find(
+        (message) => message.role === 'tool',
+      )
+      const { subagentRunId } = JSON.parse(String(result?.content))
+      if (typeof subagentRunId !== 'string') throw new Error('no child yet')
+      return subagentRunId
+    })
+    const statusOf = async (path: string) =>
+      (await handler(new Request(`http://local/api/harness/${path}`))).status
+
+    const transcript = await client.agentTranscript(childId)
+
+    expect(transcript.map((message) => message.content)).toEqual([
+      'Take notes',
+      'Note 1',
+    ])
+    expect(await client.agentTranscript('unknown')).toEqual([])
+    expect(await statusOf('agent-transcript?threadId=thread-a')).toBe(400)
+    expect(
+      await statusOf(
+        `agent-transcript?threadId=someone-else&subagentRunId=${childId}`,
+      ),
+    ).toBe(403)
+    await host.close()
+  })
+
+  it('throws with the route and the status when a read fails', async () => {
+    const { host, client } = setup(
+      () => async () => new Response('down', { status: 500 }),
+    )
+
+    await expect(client.describe()).rejects.toThrow(
+      'Harness describe failed (500)',
+    )
+    await host.close()
+  })
+
+  it('reports the connection state of the event stream', async () => {
+    let calls = 0
+    const { host, client } = setup((fetch) => async (input, init) => {
+      const url = String(input instanceof Request ? input.url : input)
+      if (url.includes('/events') && calls++ === 0) {
+        return new Response('down', { status: 500 })
+      }
+      return fetch(input, init)
+    })
+    const states: Array<string> = []
+    const reader = new AbortController()
+    const reading = (async () => {
+      for await (const _entry of client.events({
+        signal: reader.signal,
+        onConnection: (state) => states.push(state),
+      })) {
+        // Only the connection states matter here.
+      }
+    })()
+
+    await vi.waitFor(() => expect(states).toEqual(['reconnecting', 'open']))
+    reader.abort()
+    await reading
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/client.test.ts b/packages/ai-harness/tests/client.test.ts
new file mode 100644
index 0000000000..919102f763
--- /dev/null
+++ b/packages/ai-harness/tests/client.test.ts
@@ -0,0 +1,239 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { defineAgent } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHandler, createHarnessHost, defineHarness } from '../src'
+import { createHarnessClient } from '../src/client'
+import { gate, messageTexts, mockAdapter, text } from './helpers'
+import type { SessionEvent } from '../src'
+
+describe('createHarnessClient', () => {
+  it('sends inputs, reads events, and gets a snapshot through the handler', async () => {
+    const pricer = defineAgent({
+      name: 'pricer',
+      description: 'Prices a vendor',
+      inputSchema: z.object({ vendor: z.string() }),
+      run: async (ctx) => ({ cents: ctx.input.vendor.length }),
+    })
+    const { adapter } = mockAdapter([() => text('hello from the host')])
+    const studio = defineHarness({
+      name: 'test/client',
+      adapter,
+      agents: [pricer],
+      expose: { agents: ['pricer'] },
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const handler = createHarnessHandler({
+      host,
+      harness: studio,
+      canAccess: () => true,
+      authorize: (request) =>
+        request.headers.get('authorization') === 'Bearer t'
+          ? { id: 'u' }
+          : null,
+    })
+    const client = createHarnessClient<typeof studio>({
+      url: 'http://local/api/harness/',
+      threadId: 'thread-c',
+      headers: { authorization: 'Bearer t' },
+      fetch: (input, init) => handler(new Request(input, init)),
+    })
+
+    const receipt = await client.prompt('hi')
+    expect(receipt.status).toBe('accepted')
+
+    const controller = new AbortController()
+    const seen: Array<SessionEvent> = []
+    for await (const entry of client.events({ signal: controller.signal })) {
+      seen.push(entry)
+      if (
+        entry.event.type === 'CUSTOM' &&
+        entry.event.name === 'harness.operation.finished'
+      ) {
+        controller.abort()
+      }
+    }
+    expect(JSON.stringify(seen)).toContain('hello from the host')
+
+    const agent = await client.agents.pricer.start({ vendor: 'acme' })
+    expect(agent.status).toBe('accepted')
+    // @ts-expect-error the input is typed from the harness
+    void client.agents.pricer.start({ vendor: 1 })
+
+    const snapshot = await client.snapshot()
+    expect(snapshot.threadId).toBe('thread-c')
+    await host.close()
+  })
+
+  it('sends an inputId, so a retry gets the first receipt', async () => {
+    const { adapter, calls } = mockAdapter([() => text('once')])
+    const studio = defineHarness({ name: 'test/client-ids', adapter })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const handler = createHarnessHandler({
+      host,
+      harness: studio,
+      canAccess: () => true,
+      authorize: () => ({ id: 'u' }),
+    })
+    const client = createHarnessClient<typeof studio>({
+      url: 'http://local/api/harness',
+      threadId: 'thread-ids',
+      fetch: (input, init) => handler(new Request(input, init)),
+    })
+
+    const first = await client.prompt('hi', { inputId: 'req-1' })
+    const retry = await client.prompt('hi', { inputId: 'req-1' })
+    const steer = await client.steer('also', { inputId: 'req-2' })
+    const steerRetry = await client.steer('also', { inputId: 'req-2' })
+
+    expect(first).toMatchObject({ inputId: 'req-1', status: 'accepted' })
+    expect(retry).toEqual(first)
+    expect(steerRetry).toEqual(steer)
+    expect(calls.length).toBeLessThanOrEqual(2)
+    await host.close()
+  })
+
+  it('sends continue, and the model answers the stored transcript', async () => {
+    const { adapter, calls } = mockAdapter([() => text('went')])
+    const studio = defineHarness({ name: 'test/client-continue', adapter })
+    const persistence = memoryPersistence()
+    await persistence.stores.messages.saveThread('thread-go', [
+      { id: 'u1', role: 'user', content: 'go' },
+    ])
+    const host = createHarnessHost({ persistence })
+    const handler = createHarnessHandler({
+      host,
+      harness: studio,
+      canAccess: () => true,
+      authorize: () => ({ id: 'u' }),
+    })
+    const client = createHarnessClient<typeof studio>({
+      url: 'http://local/api/harness',
+      threadId: 'thread-go',
+      fetch: (input, init) => handler(new Request(input, init)),
+    })
+
+    const receipt = await client.continue({ inputId: 'c-1' })
+
+    expect(receipt).toMatchObject({ inputId: 'c-1', status: 'accepted' })
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    expect(messageTexts(calls[0])).toEqual(['go'])
+    await host.close()
+  })
+
+  it('sends ephemeral messages with prompt and continue, and no store keeps them', async () => {
+    const { adapter, calls } = mockAdapter([
+      () => text('one'),
+      () => text('two'),
+    ])
+    const studio = defineHarness({ name: 'test/client-ephemeral', adapter })
+    const persistence = memoryPersistence()
+    const { messages } = persistence.stores
+    await messages.saveThread('thread-eph', [
+      { id: 'u1', role: 'user', content: 'go' },
+    ])
+    const host = createHarnessHost({ persistence })
+    const handler = createHarnessHandler({
+      host,
+      harness: studio,
+      canAccess: () => true,
+      authorize: () => ({ id: 'u' }),
+    })
+    const client = createHarnessClient<typeof studio>({
+      url: 'http://local/api/harness',
+      threadId: 'thread-eph',
+      fetch: (input, init) => handler(new Request(input, init)),
+    })
+
+    await client.continue({ ephemeral: [{ role: 'user', content: 'note 1' }] })
+    await client.prompt('again', {
+      ephemeral: [{ role: 'user', content: 'note 2' }],
+    })
+    await vi.waitFor(async () =>
+      expect(await messages.loadThread('thread-eph')).toHaveLength(4),
+    )
+
+    expect(messageTexts(calls[0])).toEqual(['go', 'note 1'])
+    expect(messageTexts(calls[1])).toEqual(['go', 'one', 'again', 'note 2'])
+    expect(
+      JSON.stringify(await messages.loadThread('thread-eph')),
+    ).not.toContain('note')
+    await host.close()
+  })
+
+  it('throws on a refused request instead of retrying', async () => {
+    const { adapter } = mockAdapter([])
+    const studio = defineHarness({ name: 'test/client-denied', adapter })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const handler = createHarnessHandler({
+      host,
+      harness: studio,
+      canAccess: () => true,
+      authorize: () => null,
+    })
+    const client = createHarnessClient<typeof studio>({
+      url: 'http://local/api/harness',
+      threadId: 't',
+      fetch: (input, init) => handler(new Request(input, init)),
+    })
+    await expect(client.prompt('hi')).rejects.toThrow('401')
+    await expect(async () => {
+      for await (const _ of client.events()) break
+    }).rejects.toThrow('401')
+    await host.close()
+  })
+})
+
+describe('client.sendToAgent', () => {
+  it('sends a message to an agent run, as the request principal', async () => {
+    const hold = gate()
+    const drafter = defineAgent({
+      name: 'drafter',
+      description: 'Drafts when the test lets it',
+      inputSchema: z.object({ topic: z.string() }),
+      run: async (ctx) => {
+        await hold.opened
+        return `a draft about ${ctx.input.topic}`
+      },
+    })
+    const studio = defineHarness({
+      name: 'test/client-agent-messages',
+      adapter: mockAdapter([]).adapter,
+      agents: [drafter],
+      expose: { agents: ['drafter'] },
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const handler = createHarnessHandler({
+      host,
+      harness: studio,
+      canAccess: () => true,
+      authorize: () => ({ id: 'u' }),
+    })
+    const client = createHarnessClient<typeof studio>({
+      url: 'http://local/api/harness',
+      threadId: 'thread-m',
+      fetch: (input, init) => handler(new Request(input, init)),
+    })
+
+    const started = await client.agents.drafter.start({ topic: 'tea' })
+    const receipt = await client.sendToAgent({
+      operationId: started.operationId ?? '',
+      message: 'Add a title.',
+      mode: 'followUp',
+      inputId: 'm-1',
+    })
+
+    expect(receipt).toMatchObject({ inputId: 'm-1', status: 'queued' })
+    const session = await host.open(studio, { threadId: 'thread-m' })
+    expect(session.agentRuns()).toMatchObject([
+      { operationId: started.operationId, agent: 'drafter' },
+      {
+        operationId: receipt.operationId,
+        status: 'queued',
+        principal: { id: 'u' },
+      },
+    ])
+    hold.open()
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/http-media.test.ts b/packages/ai-harness/tests/http-media.test.ts
new file mode 100644
index 0000000000..ac280484d8
--- /dev/null
+++ b/packages/ai-harness/tests/http-media.test.ts
@@ -0,0 +1,409 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHandler,
+  createHarnessHost,
+  defineHarness,
+  isMediaRecord,
+  mediaPart,
+} from '../src'
+import { mockAdapter, text } from './helpers'
+import type { ContentPart } from '@tanstack/ai'
+import type { Authorize, MediaOptions, MediaRecord } from '../src'
+
+const BASE = 'http://x/api/harness'
+const HOUR = 60 * 60 * 1000
+const NOW = 1_000_000
+
+const allowUser: Authorize = (request) =>
+  request.headers.get('authorization') === 'Bearer good'
+    ? { id: 'user-1' }
+    : null
+
+/**
+ * A handler for user-1, who can open only threads that start with `user-1`.
+ * `handlerWith` makes another handler on the same host.
+ */
+function setup(options: { media?: MediaOptions; mediaSecret?: string } = {}) {
+  const { adapter, calls } = mockAdapter(() => text('ok'))
+  const harness = defineHarness({
+    name: 'test/http-media',
+    adapter,
+    media: options.media,
+  })
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const handlerWith = (
+    handlerOptions: { authorize?: Authorize; mediaSecret?: string } = {},
+  ) =>
+    createHarnessHandler({
+      host,
+      harness,
+      authorize: handlerOptions.authorize ?? allowUser,
+      canAccess: (principal, threadId) => threadId.startsWith(principal.id),
+      mediaSecret: handlerOptions.mediaSecret,
+    })
+  const handler = handlerWith({ mediaSecret: options.mediaSecret })
+  const call = (path: string, init: RequestInit = {}) =>
+    handler(
+      new Request(`${BASE}/${path}`, {
+        ...init,
+        headers: { authorization: 'Bearer good', ...init.headers },
+      }),
+    )
+  const post = (path: string, body: string, contentType: string) =>
+    call(path, {
+      method: 'POST',
+      body,
+      headers: { 'content-type': contentType },
+    })
+
+  /** Upload `body` to `threadId`. */
+  const upload = async (
+    threadId: string,
+    body = 'hello',
+    mimeType = 'image/png',
+  ) => {
+    const response = await post(
+      `media?threadId=${threadId}&name=cat.png`,
+      body,
+      mimeType,
+    )
+    const record: unknown = await response.json()
+    if (!isMediaRecord(record))
+      throw new Error(`The upload failed: ${JSON.stringify(record)}`)
+    return record
+  }
+
+  /** The signed path of `record`, from the media-url route. */
+  const signedPath = async (record: MediaRecord) => {
+    const response = await call(
+      `media-url?threadId=${record.threadId}&id=${record.id}`,
+    )
+    const body: { path: string; expiresAt: number } = await response.json()
+    return body
+  }
+
+  /** A GET with no Authorization header. */
+  const fetchSigned = (path: string, target = handler) =>
+    target(new Request(`${BASE}/${path}`))
+
+  return {
+    host,
+    calls,
+    handlerWith,
+    call,
+    post,
+    upload,
+    signedPath,
+    fetchSigned,
+  }
+}
+
+/** A file of user-1-a, the query of its signed URL, and a second file. */
+async function signedFile() {
+  const env = setup()
+  const record = await env.upload('user-1-a')
+  const other = await env.upload('user-1-a', 'other')
+  const { path } = await env.signedPath(record)
+  const query = new URLSearchParams(path.slice('media?'.length))
+  return { ...env, record, other, query }
+}
+
+/** An AG-UI run body with one user message. */
+function runBody(threadId: string, content: Array<unknown>) {
+  return JSON.stringify({
+    threadId,
+    runId: 'client-run',
+    messages: [{ id: 'u1', role: 'user', content }],
+    tools: [],
+    context: [],
+    state: {},
+    forwardedProps: {},
+  })
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('media upload and signed URLs', () => {
+  it('needs mediaSecret on a durable host, where another instance verifies the URL', () => {
+    const { adapter } = mockAdapter(() => text('ok'))
+    const harness = defineHarness({ name: 'test/http-media-durable', adapter })
+    const host = createHarnessHost({
+      persistence: {
+        stores: {
+          log: memoryLogStore(),
+          runs: memoryPersistence().stores.runs,
+        },
+      },
+    })
+    const options = {
+      host,
+      harness,
+      authorize: allowUser,
+      canAccess: () => true,
+    }
+    expect(() => createHarnessHandler(options)).toThrow(/mediaSecret/)
+    expect(() =>
+      createHarnessHandler({ ...options, mediaSecret: 'shared' }),
+    ).not.toThrow()
+  })
+
+  it('stores an upload, signs its URL for 1 hour, and serves the signed URL without auth', async () => {
+    vi.useFakeTimers({ toFake: ['Date'], now: NOW })
+    const { host, upload, signedPath, fetchSigned } = setup()
+
+    const record = await upload('user-1-a')
+    const { path, expiresAt } = await signedPath(record)
+    const response = await fetchSigned(path)
+
+    expect(record).toEqual({
+      id: expect.any(String),
+      threadId: 'user-1-a',
+      kind: 'image',
+      mimeType: 'image/png',
+      name: 'cat.png',
+      size: 5,
+      source: 'user',
+      createdAt: NOW,
+    })
+    expect(expiresAt).toBe(NOW + HOUR)
+    expect(path).toMatch(
+      new RegExp(
+        `^media\\?threadId=user-1-a&id=${record.id}&exp=${NOW + HOUR}&sig=[\\w-]+$`,
+      ),
+    )
+    expect(response.status).toBe(200)
+    expect(await response.text()).toBe('hello')
+    await host.close()
+  })
+
+  it('serves a signed URL through a handler whose authorize refuses everything', async () => {
+    const { host, upload, signedPath, fetchSigned, handlerWith } = setup({
+      mediaSecret: 'shared',
+    })
+    const record = await upload('user-1-a')
+    const { path } = await signedPath(record)
+    const refuseAll = handlerWith({
+      authorize: () => null,
+      mediaSecret: 'shared',
+    })
+
+    const signed = await fetchSigned(path, refuseAll)
+    const unsigned = await fetchSigned(
+      `media?threadId=user-1-a&id=${record.id}`,
+      refuseAll,
+    )
+
+    expect(signed.status).toBe(200)
+    expect(await signed.text()).toBe('hello')
+    expect(unsigned.status).toBe(401)
+    await host.close()
+  })
+
+  const tampered: Array<{
+    label: string
+    change: (query: URLSearchParams, other: MediaRecord) => void
+  }> = [
+    {
+      label: 'another file id',
+      change: (query, other) => query.set('id', other.id),
+    },
+    {
+      label: 'another thread',
+      change: (query) => query.set('threadId', 'user-1-b'),
+    },
+    {
+      label: 'a later expiry',
+      change: (query) => query.set('exp', String(Date.now() + 2 * HOUR)),
+    },
+  ]
+
+  it.each(tampered)(
+    'refuses the signature of a URL with $label (403)',
+    async ({ change }) => {
+      const { host, query, other, fetchSigned } = await signedFile()
+
+      change(query, other)
+      const response = await fetchSigned(`media?${query}`)
+
+      expect(response.status).toBe(403)
+      await host.close()
+    },
+  )
+
+  it('refuses a signed URL after it expires (403)', async () => {
+    vi.useFakeTimers({ toFake: ['Date'], now: NOW })
+    const { host, query, fetchSigned } = await signedFile()
+
+    vi.setSystemTime(NOW + HOUR + 1)
+    const response = await fetchSigned(`media?${query}`)
+
+    expect(response.status).toBe(403)
+    await host.close()
+  })
+
+  it('refuses a URL signed by a handler with another random key (403)', async () => {
+    const { host, query, fetchSigned, handlerWith } = await signedFile()
+
+    const response = await fetchSigned(`media?${query}`, handlerWith())
+
+    expect(response.status).toBe(403)
+    await host.close()
+  })
+
+  it('does not sign or serve the file of another thread (404)', async () => {
+    const { host, call, upload } = setup()
+    const record = await upload('user-1-a')
+
+    const url = await call(`media-url?threadId=user-1-b&id=${record.id}`)
+    const bytes = await call(`media?threadId=user-1-b&id=${record.id}`)
+
+    expect(url.status).toBe(404)
+    expect(bytes.status).toBe(404)
+    await host.close()
+  })
+
+  it('serves an unsigned GET only to a principal that can open the thread', async () => {
+    const { host, call, upload, fetchSigned } = setup()
+    const record = await upload('user-1-a')
+    const path = `media?threadId=user-1-a&id=${record.id}`
+
+    const owner = await call(path)
+
+    expect(owner.status).toBe(200)
+    expect(await owner.text()).toBe('hello')
+    expect((await fetchSigned(path)).status).toBe(401)
+    expect(
+      (await call(`media?threadId=someone-else&id=${record.id}`)).status,
+    ).toBe(403)
+    await host.close()
+  })
+
+  it('refuses a file over media.maxBytes (413)', async () => {
+    const { host, post } = setup({ media: { maxBytes: 4 } })
+
+    const response = await post(
+      'media?threadId=user-1-a&name=cat.png',
+      'hello',
+      'image/png',
+    )
+
+    expect(response.status).toBe(413)
+    expect(await response.json()).toEqual({
+      error: 'The file is bigger than the limit of 4 bytes.',
+    })
+    await host.close()
+  })
+
+  it('refuses a type that is not media (415)', async () => {
+    const { host, post } = setup()
+
+    const response = await post(
+      'media?threadId=user-1-a&name=a.zip',
+      'PK',
+      'application/zip',
+    )
+
+    expect(response.status).toBe(415)
+    expect(await response.json()).toEqual({
+      error: 'Files of type application/zip are not supported.',
+    })
+    await host.close()
+  })
+})
+
+describe('media bytes', () => {
+  it('answers a Range request with 206 and the slice', async () => {
+    const { host, call, upload } = setup()
+    const record = await upload('user-1-a')
+
+    const response = await call(`media?threadId=user-1-a&id=${record.id}`, {
+      headers: { range: 'bytes=1-3' },
+    })
+
+    expect(response.status).toBe(206)
+    expect(response.headers.get('content-range')).toBe('bytes 1-3/5')
+    expect(response.headers.get('content-length')).toBe('3')
+    expect(await response.text()).toBe('ell')
+    await host.close()
+  })
+
+  it('answers a Range past the end with 416', async () => {
+    const { host, call, upload } = setup()
+    const record = await upload('user-1-a')
+
+    const response = await call(`media?threadId=user-1-a&id=${record.id}`, {
+      headers: { range: 'bytes=5-' },
+    })
+
+    expect(response.status).toBe(416)
+    expect(response.headers.get('content-range')).toBe('bytes */5')
+    await host.close()
+  })
+
+  it('serves a document so that it cannot run as a page of this origin', async () => {
+    const { host, upload, signedPath, fetchSigned } = setup()
+    const page = '<script>alert(1)</script>'
+    const record = await upload('user-1-a', page, 'text/html')
+    const { path } = await signedPath(record)
+
+    const response = await fetchSigned(path)
+
+    expect(Object.fromEntries(response.headers)).toEqual({
+      'accept-ranges': 'bytes',
+      'content-length': String(page.length),
+      'content-security-policy': "default-src 'none'; sandbox",
+      'content-type': 'text/html',
+      'x-content-type-options': 'nosniff',
+    })
+    await host.close()
+  })
+})
+
+describe('POST run with media parts', () => {
+  // AG-UI text parts carry `text`. Media parts have the TanStack shape.
+  const question = { type: 'text', text: 'What is this?' }
+  // 'aGVsbG8=' is base64 for "hello", the bytes of every upload here.
+  const data: ContentPart = {
+    type: 'image',
+    source: { type: 'data', value: 'aGVsbG8=', mimeType: 'image/png' },
+  }
+
+  const cases: Array<{
+    label: string
+    part: (record: MediaRecord) => ContentPart
+  }> = [
+    { label: 'a harness-media URL, and keeps the URL', part: mediaPart },
+    { label: 'a data part, and keeps it as sent', part: () => data },
+  ]
+
+  it.each(cases)(
+    'gives the model the bytes of $label in the transcript',
+    async ({ part }) => {
+      const { host, call, upload, calls } = setup()
+      const record = await upload('user-1-run')
+
+      const response = await call('run', {
+        method: 'POST',
+        body: runBody('user-1-run', [question, part(record)]),
+        headers: { 'content-type': 'application/json' },
+      })
+      await response.text()
+      const transcript = await (
+        await call('transcript?threadId=user-1-run')
+      ).json()
+
+      expect(calls[0].messages[0].content).toEqual([
+        { type: 'text', content: 'What is this?' },
+        data,
+      ])
+      expect(transcript[0].content).toEqual([
+        { type: 'text', content: 'What is this?' },
+        part(record),
+      ])
+      await host.close()
+    },
+  )
+})
diff --git a/packages/ai-harness/tests/oauth-edges.test.ts b/packages/ai-harness/tests/oauth-edges.test.ts
new file mode 100644
index 0000000000..f8aba7fecf
--- /dev/null
+++ b/packages/ai-harness/tests/oauth-edges.test.ts
@@ -0,0 +1,341 @@
+import { describe, expect, it } from 'vitest'
+import { toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  AuthRequiredError,
+  buildAuthorizationUrl,
+  createHarnessHost,
+  defineHarness,
+  deviceLogin,
+  exchangeCode,
+  isExpired,
+  loopbackLogin,
+  oauthConnector,
+  refreshCredential,
+  scrubSecrets,
+} from '../src'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { OAuthConfig } from '../src'
+
+const oauth: OAuthConfig = {
+  authorizationUrl: 'https://auth.example/authorize',
+  tokenUrl: 'https://auth.example/token',
+  deviceUrl: 'https://auth.example/device',
+  clientId: 'client-1',
+}
+
+/** A fetch that answers each call with the next body, and records the forms. */
+function replies(bodies: Array<unknown>, status = 200) {
+  const forms: Array<URLSearchParams> = []
+  const fake: typeof fetch = async (_input, init) => {
+    forms.push(new URLSearchParams(String(init?.body ?? '')))
+    const body = bodies.shift()
+    return new Response(
+      typeof body === 'string' ? body : JSON.stringify(body),
+      {
+        status,
+      },
+    )
+  }
+  return { fake, forms }
+}
+
+describe('token requests', () => {
+  it('sends the client secret and keeps the old refresh token', async () => {
+    const { fake, forms } = replies([
+      { access_token: 'a2', expires_in: 60, scope: 'repo,read:user' },
+    ])
+    const refreshed = await refreshCredential(
+      { ...oauth, clientSecret: 'shh' },
+      { type: 'oauth', accessToken: 'a1', refreshToken: 'r1' },
+      fake,
+    )
+    expect(forms[0]?.get('client_secret')).toBe('shh')
+    expect(refreshed).toMatchObject({
+      type: 'oauth',
+      accessToken: 'a2',
+      refreshToken: 'r1',
+      scopes: ['repo', 'read:user'],
+    })
+    expect(refreshed.type === 'oauth' && refreshed.expiresAt).toBeGreaterThan(
+      Date.now(),
+    )
+  })
+
+  it('refuses a credential without a refresh token', async () => {
+    await expect(
+      refreshCredential(oauth, { type: 'oauth', accessToken: 'a' }),
+    ).rejects.toThrow('no refresh token')
+    await expect(
+      refreshCredential(oauth, { type: 'api_key', value: 'k' }),
+    ).rejects.toThrow('no refresh token')
+  })
+
+  it('reports bodies that are not token objects', async () => {
+    const options = { code: 'c', verifier: 'v', redirectUri: 'http://x' }
+    await expect(
+      exchangeCode(oauth, { ...options, fetch: replies(['"text"'], 500).fake }),
+    ).rejects.toThrow('OAuth token request failed (500).')
+    await expect(
+      exchangeCode(oauth, { ...options, fetch: replies(['not json']).fake }),
+    ).rejects.toThrow('no access_token')
+  })
+
+  it('knows when a credential expires', () => {
+    expect(isExpired({ type: 'api_key', value: 'k' })).toBe(false)
+    expect(isExpired({ type: 'oauth', accessToken: 'a' })).toBe(false)
+    expect(
+      isExpired({
+        type: 'oauth',
+        accessToken: 'a',
+        expiresAt: Date.now() + 30_000,
+      }),
+    ).toBe(true)
+    expect(
+      isExpired(
+        { type: 'oauth', accessToken: 'a', expiresAt: Date.now() + 30_000 },
+        0,
+      ),
+    ).toBe(false)
+  })
+
+  it('leaves the scope out of the URL when there is none', () => {
+    const url = new URL(
+      buildAuthorizationUrl(oauth, {
+        redirectUri: 'http://127.0.0.1:1/callback',
+        state: 's',
+        challenge: 'c',
+      }),
+    )
+    expect(url.searchParams.has('scope')).toBe(false)
+  })
+})
+
+describe('loopbackLogin edges', () => {
+  async function login(
+    callback: (redirect: URL, state: string) => string,
+    options: { timeoutMs?: number } = {},
+  ) {
+    const { fake } = replies([{ access_token: 'token' }])
+    return loopbackLogin(oauth, {
+      fetch: fake,
+      ...options,
+      onUrl: (value) => {
+        const url = new URL(value)
+        const redirect = new URL(url.searchParams.get('redirect_uri') ?? '')
+        const state = url.searchParams.get('state') ?? ''
+        void (async () => {
+          // A request to another path does not end the sign-in.
+          await fetch(new URL('/favicon.ico', redirect))
+          await fetch(callback(redirect, state))
+        })()
+      },
+    })
+  }
+
+  it('reports the error from the server and a missing code', async () => {
+    await expect(
+      login(
+        (redirect, state) => `${redirect}?state=${state}&error=access_denied`,
+      ),
+    ).rejects.toThrow('Sign-in failed: access_denied')
+    await expect(
+      login((redirect, state) => `${redirect}?state=${state}`),
+    ).rejects.toThrow('Sign-in failed: no code')
+  })
+
+  it('times out when nobody comes back', async () => {
+    await expect(
+      loopbackLogin(oauth, { onUrl: () => {}, timeoutMs: 10 }),
+    ).rejects.toThrow('Sign-in timed out.')
+  })
+})
+
+describe('deviceLogin edges', () => {
+  const noSleep = async () => {}
+
+  it('needs a device endpoint and a device code', async () => {
+    await expect(
+      deviceLogin({ ...oauth, deviceUrl: undefined }, { onCode: () => {} }),
+    ).rejects.toThrow('no device endpoint')
+    await expect(
+      deviceLogin(oauth, {
+        onCode: () => {},
+        fetch: replies([{ user_code: 'X' }]).fake,
+        sleep: noSleep,
+      }),
+    ).rejects.toThrow('no device code')
+  })
+
+  it('slows down when asked, sends scopes, and falls back to the authorization URL', async () => {
+    const waits: Array<number> = []
+    const shown: Array<string> = []
+    const { fake, forms } = replies([
+      { device_code: 'd', user_code: 'CODE' },
+      { error: 'slow_down' },
+      { error: 'authorization_pending' },
+      { access_token: 'granted' },
+    ])
+    const credential = await deviceLogin(
+      { ...oauth, scopes: ['repo'] },
+      {
+        onCode: (info) =>
+          shown.push(`${info.userCode} ${info.verificationUri}`),
+        fetch: fake,
+        sleep: async (ms) => {
+          waits.push(ms)
+        },
+      },
+    )
+    expect(forms[0]?.get('scope')).toBe('repo')
+    expect(shown).toEqual(['CODE https://auth.example/authorize'])
+    expect(waits).toEqual([5000, 10000, 10000])
+    expect(credential).toMatchObject({ accessToken: 'granted' })
+  })
+
+  it('stops when the device code expires', async () => {
+    const { fake } = replies([
+      { device_code: 'd', user_code: 'C', expires_in: 0, interval: 0 },
+    ])
+    await expect(
+      deviceLogin(oauth, { onCode: () => {}, fetch: fake, sleep: noSleep }),
+    ).rejects.toThrow('Device sign-in expired.')
+  })
+})
+
+describe('oauthConnector edges', () => {
+  function connector(fetchFn: typeof fetch, seen: Array<string>) {
+    return oauthConnector({
+      id: 'svc',
+      label: 'Service',
+      login: 'loopback',
+      oauth,
+      fetch: fetchFn,
+      tools: (token) => [
+        toolDefinition({ name: 'whoami', description: 'Who am I' }).server(
+          async () => {
+            seen.push(await token())
+            return 'me'
+          },
+        ),
+      ],
+    })
+  }
+
+  it('refreshes an expired token, and passes an API key through', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.credentials.set({
+      scope: { threadId: 't1', userId: 'u1' },
+      id: 'svc',
+      credential: {
+        type: 'oauth',
+        accessToken: 'old',
+        refreshToken: 'r',
+        expiresAt: Date.now() - 1,
+      },
+    })
+    await persistence.stores.credentials.set({
+      scope: { threadId: 't2', userId: 'u2' },
+      id: 'svc',
+      credential: {
+        type: 'api_key',
+        value: 'key-1',
+      },
+    })
+    const seen: Array<string> = []
+    const { fake } = replies([{ access_token: 'fresh', expires_in: 3600 }])
+    const { adapter } = mockAdapter([
+      () => toolCall('whoami', {}),
+      () => text('done'),
+      () => toolCall('whoami', {}),
+      () => text('done'),
+    ])
+    const host = createHarnessHost({ persistence })
+    const harness = defineHarness({
+      name: 'test/refresh',
+      adapter,
+      plugins: () => [connector(fake, seen)],
+    })
+    await (
+      await host.open(harness, { threadId: 't1', principal: { id: 'u1' } })
+    ).prompt('who')
+    await (
+      await host.open(harness, { threadId: 't2', principal: { id: 'u2' } })
+    ).prompt('who')
+    expect(seen).toEqual(['fresh', 'key-1'])
+    expect(
+      await persistence.stores.credentials.get({
+        scope: { threadId: 't1', userId: 'u1' },
+        id: 'svc',
+      }),
+    ).toMatchObject({ accessToken: 'fresh', refreshToken: 'r' })
+    await host.close()
+  })
+
+  it('signs in through the loopback and signs out', async () => {
+    const persistence = memoryPersistence()
+    const { fake } = replies([{ access_token: 'loop-token' }])
+    const host = createHarnessHost({ persistence })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/loopback-connector',
+        adapter: mockAdapter([]).adapter,
+        plugins: () => [connector(fake, [])],
+      }),
+      { threadId: 't' },
+    )
+    const controller = new AbortController()
+    const signIn = (async () => {
+      for await (const entry of session.events({ signal: controller.signal })) {
+        const value =
+          entry.event.type === 'CUSTOM' ? entry.event.value : undefined
+        if (
+          typeof value === 'object' &&
+          value !== null &&
+          'url' in value &&
+          typeof value.url === 'string'
+        ) {
+          const url = new URL(value.url)
+          const redirect = url.searchParams.get('redirect_uri') ?? ''
+          const state = url.searchParams.get('state') ?? ''
+          await fetch(`${redirect}?code=c&state=${state}`)
+          return
+        }
+      }
+    })()
+    expect(await session.command('connect:svc')).toBe('Connected to Service.')
+    controller.abort()
+    await signIn
+    expect(
+      await persistence.stores.credentials.get({
+        scope: { threadId: 't' },
+        id: 'svc',
+      }),
+    ).toMatchObject({ accessToken: 'loop-token' })
+    expect(await session.command('disconnect:svc')).toBe(
+      'Disconnected from Service.',
+    )
+    expect(
+      await persistence.stores.credentials.get({
+        scope: { threadId: 't' },
+        id: 'svc',
+      }),
+    ).toBeNull()
+    await host.close()
+  })
+})
+
+describe('auth helpers', () => {
+  it('describes the sign-in in the error, with and without a URL', () => {
+    expect(new AuthRequiredError('svc').message).toContain('/connect svc')
+    const withUrl = new AuthRequiredError('svc', 'https://x/login')
+    expect(withUrl.message).toContain('https://x/login')
+    expect(withUrl.url).toBe('https://x/login')
+  })
+
+  it('keeps short strings when scrubbing', () => {
+    expect(
+      scrubSecrets('pin 12345 and token abcdef', ['12345', 'abcdef']),
+    ).toBe('pin 12345 and token [redacted]')
+  })
+})
diff --git a/packages/ai-harness/tests/oauth-loopback.test.ts b/packages/ai-harness/tests/oauth-loopback.test.ts
new file mode 100644
index 0000000000..23b4e03dbe
--- /dev/null
+++ b/packages/ai-harness/tests/oauth-loopback.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest'
+import { startLoopbackReceiver } from '../src'
+
+describe('startLoopbackReceiver', () => {
+  it('returns the code for the matching state and ignores other paths', async () => {
+    const receiver = await startLoopbackReceiver()
+    expect(receiver.redirectUri).toMatch(
+      /^http:\/\/127\.0\.0\.1:\d+\/callback$/,
+    )
+    const code = receiver.waitForCode('s1')
+    const other = await fetch(
+      receiver.redirectUri.replace('/callback', '/favicon.ico'),
+    )
+    expect(other.status).toBe(404)
+    const done = await fetch(`${receiver.redirectUri}?code=abc&state=s1`)
+    expect(done.status).toBe(200)
+    expect(await done.text()).toContain('signed in')
+    expect(await code).toEqual({ code: 'abc' })
+  })
+
+  it('returns the issuer the server sent with the code (RFC 9207)', async () => {
+    const receiver = await startLoopbackReceiver()
+    const code = receiver.waitForCode('s1')
+    const issuer = encodeURIComponent('https://mcp.linear.app')
+    await fetch(`${receiver.redirectUri}?code=abc&state=s1&iss=${issuer}`)
+    expect(await code).toEqual({ code: 'abc', iss: 'https://mcp.linear.app' })
+  })
+
+  it('refuses a callback with the wrong state', async () => {
+    const receiver = await startLoopbackReceiver()
+    const code = receiver.waitForCode('expected')
+    const rejected = expect(code).rejects.toThrow('the state does not match')
+    await fetch(`${receiver.redirectUri}?code=abc&state=other`)
+    await rejected
+  })
+
+  it('reports the error the server sent back', async () => {
+    const receiver = await startLoopbackReceiver()
+    const code = receiver.waitForCode('s')
+    const rejected = expect(code).rejects.toThrow(
+      'Sign-in failed: access_denied',
+    )
+    await fetch(`${receiver.redirectUri}?error=access_denied&state=s`)
+    await rejected
+
+    const bare = await startLoopbackReceiver()
+    const noCode = bare.waitForCode('s')
+    const missing = expect(noCode).rejects.toThrow('Sign-in failed: no code')
+    await fetch(`${bare.redirectUri}?state=s`)
+    await missing
+  })
+
+  it('times out and stops listening', async () => {
+    const receiver = await startLoopbackReceiver({ timeoutMs: 20 })
+    await expect(receiver.waitForCode('s')).rejects.toThrow(
+      'Sign-in timed out.',
+    )
+    await expect(fetch(receiver.redirectUri)).rejects.toThrow()
+    receiver.close()
+  })
+})
diff --git a/packages/ai-harness/tests/protocol.test.ts b/packages/ai-harness/tests/protocol.test.ts
new file mode 100644
index 0000000000..7532aa3e8c
--- /dev/null
+++ b/packages/ai-harness/tests/protocol.test.ts
@@ -0,0 +1,479 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { defineAgent } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHandler,
+  createHarnessHost,
+  defineHarness,
+  handleHarnessSocket,
+  parseControlFrame,
+  parseHarnessInput,
+} from '../src'
+import { after, gate, mockAdapter, text, wakeMessages } from './helpers'
+import type { WebSocketLike } from '@tanstack/ai'
+import type { HostFrame } from '../src'
+import type { Reply } from './helpers'
+
+const pricer = defineAgent({
+  name: 'pricer',
+  description: 'Prices a vendor',
+  inputSchema: z.object({ vendor: z.string() }),
+  run: async (ctx) => ({ vendor: ctx.input.vendor, cents: 1200 }),
+})
+const secret = defineAgent({
+  name: 'secret',
+  description: 'Not for clients',
+  run: async () => 'hidden',
+})
+
+function setup(
+  replies: Array<Reply> = [() => text('hello'), () => text('again')],
+) {
+  const { adapter, calls } = mockAdapter(replies)
+  const harness = defineHarness({
+    name: 'test/protocol',
+    adapter,
+    agents: [pricer, secret],
+    expose: { agents: ['pricer'] },
+  })
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const handler = createHarnessHandler({
+    host,
+    harness,
+    authorize: (request) =>
+      request.headers.get('authorization') === 'Bearer good'
+        ? { id: 'user-1' }
+        : null,
+    canAccess: (principal, threadId) => threadId.startsWith(principal.id),
+  })
+  return { handler, host, harness, calls }
+}
+
+const auth = { authorization: 'Bearer good' }
+
+type Handler = ReturnType<typeof setup>['handler']
+
+/** POST one input to `/control` for `threadId`. Resolves to the JSON body. */
+function controlOf(handler: Handler, threadId: string) {
+  return async (input: unknown): Promise<unknown> =>
+    (
+      await handler(
+        new Request('http://x/api/harness/control', {
+          method: 'POST',
+          headers: { ...auth, 'content-type': 'application/json' },
+          body: JSON.stringify({ threadId, input }),
+        }),
+      )
+    ).json()
+}
+
+const isTurnEnd = (frame: HostFrame) =>
+  frame.type === 'harness.event' &&
+  frame.event.type === 'CUSTOM' &&
+  frame.event.name === 'harness.operation.finished'
+
+async function readSse(
+  response: Response,
+  until: (frame: HostFrame) => boolean,
+) {
+  if (!response.body) throw new Error('The response has no body.')
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder()
+  const frames: Array<HostFrame> = []
+  let buffer = ''
+  while (true) {
+    const { value, done } = await reader.read()
+    if (done) break
+    buffer += decoder.decode(value, { stream: true })
+    const blocks = buffer.split('\n\n')
+    buffer = blocks.pop() ?? ''
+    for (const block of blocks) {
+      const data = block
+        .split('\n')
+        .find((line) => line.startsWith('data: '))
+        ?.slice(6)
+      if (!data) continue
+      // The handler writes each frame as JSON.
+      const parsed: HostFrame = JSON.parse(data)
+      frames.push(parsed)
+      if (until(parsed)) {
+        await reader.cancel()
+        return frames
+      }
+    }
+  }
+  return frames
+}
+
+describe('HTTP handler', () => {
+  it('refuses requests that authorize rejects', async () => {
+    const { handler, host } = setup()
+    const response = await handler(
+      new Request('http://x/api/harness/capabilities'),
+    )
+    expect(response.status).toBe(401)
+    await host.close()
+  })
+
+  it('refuses threads the principal cannot access', async () => {
+    const { handler, host } = setup()
+    const response = await handler(
+      new Request('http://x/api/harness/snapshot?threadId=other-thread', {
+        headers: auth,
+      }),
+    )
+    expect(response.status).toBe(403)
+    await host.close()
+  })
+
+  it('lists only exposed agents in the capabilities', async () => {
+    const { handler, host } = setup()
+    const response = await handler(
+      new Request('http://x/api/harness/capabilities', { headers: auth }),
+    )
+    const body = await response.json()
+    expect(body.identity.name).toBe('test/protocol')
+    expect(
+      body.custom.tanstack.agents.map((agent: { name: string }) => agent.name),
+    ).toEqual(['pricer'])
+    expect(
+      body.custom.tanstack.agents[0].inputSchema.properties.vendor.type,
+    ).toBe('string')
+    await host.close()
+  })
+
+  it('serves a standard AG-UI run as SSE', async () => {
+    const { handler, host } = setup()
+    const response = await handler(
+      new Request('http://x/api/harness/run', {
+        method: 'POST',
+        headers: { ...auth, 'content-type': 'application/json' },
+        body: JSON.stringify({
+          threadId: 'user-1-thread',
+          runId: 'client-run',
+          messages: [{ id: 'm1', role: 'user', content: 'hi' }],
+          tools: [],
+          context: [],
+          state: {},
+          forwardedProps: {},
+        }),
+      }),
+    )
+    expect(response.headers.get('content-type')).toContain('text/event-stream')
+    const text = await response.text()
+    expect(text).toContain('"delta":"hello"')
+    expect(text).toContain('RUN_FINISHED')
+    await host.close()
+  })
+
+  it('takes control inputs, streams session events, and resumes from a cursor', async () => {
+    const { handler, host } = setup()
+    const control = controlOf(handler, 'user-1-t')
+
+    expect(await control({ op: 'prompt', message: 'hi' })).toMatchObject({
+      status: 'accepted',
+    })
+
+    const first = await readSse(
+      await handler(
+        new Request('http://x/api/harness/events?threadId=user-1-t', {
+          headers: auth,
+        }),
+      ),
+      isTurnEnd,
+    )
+    expect(first.every((frame) => frame.type === 'harness.event')).toBe(true)
+    const last = first.at(-1)
+    const cursor = last?.type === 'harness.event' ? last.cursor : ''
+
+    await control({ op: 'prompt', message: 'more' })
+    const second = await readSse(
+      await handler(
+        new Request('http://x/api/harness/events?threadId=user-1-t', {
+          headers: { ...auth, 'Last-Event-ID': cursor },
+        }),
+      ),
+      isTurnEnd,
+    )
+    expect(
+      second.every(
+        (frame) =>
+          frame.type === 'harness.event' &&
+          Number(frame.cursor) > Number(cursor),
+      ),
+    ).toBe(true)
+    expect(JSON.stringify(second)).toContain('again')
+    await host.close()
+  })
+
+  it('answers a retried prompt with the same inputId with the first receipt', async () => {
+    const { handler, host, calls } = setup()
+    const control = controlOf(handler, 'user-1-retry')
+
+    const first = await control({ op: 'prompt', message: 'hi', inputId: 'c-1' })
+    const retry = await control({ op: 'prompt', message: 'hi', inputId: 'c-1' })
+
+    expect(first).toMatchObject({ inputId: 'c-1', status: 'accepted' })
+    expect(retry).toEqual(first)
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    expect(
+      await control({ op: 'prompt', message: 'another', inputId: 'c-1' }),
+    ).toMatchObject({ status: 'rejected', reason: 'conflict' })
+    expect(await control({ op: 'prompt', message: 'x', inputId: 7 })).toEqual({
+      error: 'Invalid input: inputId must be a string.',
+    })
+    await host.close()
+  })
+
+  it('runs exposed agents from a client and refuses the others', async () => {
+    const { handler, host } = setup()
+    const control = controlOf(handler, 'user-1-a')
+
+    expect(await control({ op: 'agent', agent: 'secret' })).toMatchObject({
+      status: 'rejected',
+      reason: 'not_exposed',
+    })
+    expect(
+      await control({ op: 'agent', agent: 'pricer', input: { vendor: 'x' } }),
+    ).toMatchObject({
+      status: 'accepted',
+    })
+    expect(await control({ op: 'launch' })).toMatchObject({
+      error: expect.stringContaining('Invalid input'),
+    })
+    await host.close()
+  })
+
+  it('sends messages to runs of exposed agents only', async () => {
+    const { handler, host, harness } = setup()
+    const control = async (input: unknown) =>
+      (
+        await handler(
+          new Request('http://x/api/harness/control', {
+            method: 'POST',
+            headers: { ...auth, 'content-type': 'application/json' },
+            body: JSON.stringify({ threadId: 'user-1-m', input }),
+          }),
+        )
+      ).json()
+
+    const started = await control({
+      op: 'agent',
+      agent: 'pricer',
+      input: { vendor: 'x' },
+    })
+    expect(
+      await control({
+        op: 'agentMessage',
+        operationId: started.operationId,
+        message: 'In euros.',
+        mode: 'followUp',
+      }),
+    ).toMatchObject({ status: expect.stringMatching(/^(accepted|queued)$/) })
+
+    const session = await host.open(harness, { threadId: 'user-1-m' })
+    const hidden = session.agent('secret')?.start()
+    expect(
+      await control({
+        op: 'agentMessage',
+        operationId: hidden?.id,
+        message: 'Hello.',
+      }),
+    ).toMatchObject({ status: 'rejected', reason: 'not_exposed' })
+    expect(
+      await control({
+        op: 'agentMessage',
+        operationId: 'op-agent-none',
+        message: 'Hello.',
+      }),
+    ).toMatchObject({ status: 'rejected', reason: 'not_running' })
+    expect(await control({ op: 'agentMessage', message: 'Hello.' })).toEqual({
+      error: 'Invalid input: agentMessage needs an operationId.',
+    })
+    await host.close()
+  })
+
+  it('moves and cancels a waiting input, and the snapshot lists it', async () => {
+    const release = gate()
+    const { handler, host, calls } = setup([after(release.opened, 'hello')])
+    const control = controlOf(handler, 'user-1-wait')
+    const snapshot = async () =>
+      (
+        await handler(
+          new Request('http://x/api/harness/snapshot?threadId=user-1-wait', {
+            headers: auth,
+          }),
+        )
+      ).json()
+    await control({ op: 'prompt', message: 'hi' })
+    // The model call runs, so a steer can join only at a later call.
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    await control({ op: 'followUp', message: 'later', inputId: 'f-1' })
+
+    expect(
+      await control({ op: 'setDelivery', inputId: 'f-1', delivery: 'steer' }),
+    ).toMatchObject({ status: 'accepted' })
+    expect(await snapshot()).toMatchObject({
+      waitingInputs: [{ inputId: 'f-1', delivery: 'steer', message: 'later' }],
+    })
+    expect(await control({ op: 'cancelInput', inputId: 'f-1' })).toMatchObject({
+      status: 'accepted',
+    })
+    expect(await snapshot()).toMatchObject({ waitingInputs: [] })
+    expect(await control({ op: 'cancelInput', inputId: 'f-1' })).toMatchObject({
+      status: 'rejected',
+      reason: 'not_waiting',
+    })
+    release.open()
+    await host.close()
+  })
+
+  it('drops the wake mark of a client follow-up', async () => {
+    const { handler, host, harness, calls } = setup([() => text('ok')])
+    const control = controlOf(handler, 'user-1-wake')
+
+    await control({ op: 'followUp', message: 'I am real', wake: true })
+
+    await vi.waitFor(() => expect(calls).toHaveLength(1))
+    const session = await host.open(harness, { threadId: 'user-1-wake' })
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+    expect(wakeMessages(await session.transcript())).toEqual([])
+    await host.close()
+  })
+})
+
+describe('parseHarnessInput', () => {
+  it('drops the wake mark of a follow-up, which only the harness sets', () => {
+    expect(
+      parseHarnessInput({ op: 'followUp', message: 'hi', wake: true }),
+    ).toEqual({ op: 'followUp', message: 'hi' })
+  })
+
+  it('lets a client send background without an expose entry', async () => {
+    const { handler, host } = setup()
+    const control = controlOf(handler, 'user-1-bg')
+    expect(await control({ op: 'background' })).toMatchObject({
+      status: 'rejected',
+      reason: 'not_running',
+    })
+    expect(() =>
+      parseHarnessInput({ op: 'background', toolCallId: 1 }),
+    ).toThrow('Invalid input: the toolCallId of background must be a string.')
+    await host.close()
+  })
+
+  it('checks the fields of cancelInput and setDelivery', () => {
+    expect(() => parseHarnessInput({ op: 'cancelInput' })).toThrow(
+      'Invalid input: cancelInput needs an inputId.',
+    )
+    expect(() =>
+      parseHarnessInput({ op: 'setDelivery', inputId: 'a', delivery: 'now' }),
+    ).toThrow("Invalid input: setDelivery needs 'steer' or 'queue'.")
+  })
+
+  it('checks the ephemeral messages of prompt and continue', () => {
+    const refused =
+      'Invalid input: ephemeral must be an array of user messages.'
+    expect(() =>
+      parseHarnessInput({ op: 'prompt', message: 'hi', ephemeral: 'note' }),
+    ).toThrow(refused)
+    // A client cannot fake an answer or a tool result.
+    for (const role of ['system', 'assistant', 'tool']) {
+      expect(() =>
+        parseHarnessInput({
+          op: 'continue',
+          ephemeral: [{ role, content: 'note' }],
+        }),
+      ).toThrow(refused)
+    }
+    const ephemeral = [{ role: 'user', content: 'note' }]
+    expect(parseHarnessInput({ op: 'continue', ephemeral })).toEqual({
+      op: 'continue',
+      ephemeral,
+    })
+  })
+})
+
+describe('WebSocket', () => {
+  function fakeSocket() {
+    const handlers: Record<string, Array<(event?: any) => void>> = {}
+    const sent: Array<HostFrame> = []
+    const socket: WebSocketLike = {
+      send: (data) => sent.push(JSON.parse(data)),
+      close: () => handlers.close?.forEach((handler) => handler()),
+      addEventListener: (type: string, handler: (event?: any) => void) => {
+        ;(handlers[type] ??= []).push(handler)
+      },
+    }
+    const receive = (frame: unknown) =>
+      handlers.message?.forEach((handler) =>
+        handler({ data: JSON.stringify(frame) }),
+      )
+    return { socket, sent, receive }
+  }
+
+  it('subscribes, applies inputs with receipts, and streams events', async () => {
+    const { host, harness } = setup()
+    const { socket, sent, receive } = fakeSocket()
+    handleHarnessSocket({
+      host,
+      harness,
+      socket,
+      principal: { id: 'user-1' },
+      canAccess: () => true,
+    })
+
+    receive({
+      type: 'harness.input',
+      requestId: 'r0',
+      input: { op: 'prompt', message: 'x' },
+    })
+    await vi.waitFor(() => expect(sent.at(-1)?.type).toBe('harness.error'))
+
+    receive({ type: 'harness.subscribe', threadId: 'user-1-ws' })
+    await vi.waitFor(() =>
+      expect(sent.some((frame) => frame.type === 'harness.hello')).toBe(true),
+    )
+    receive({
+      type: 'harness.input',
+      requestId: 'r1',
+      input: { op: 'prompt', message: 'hi' },
+    })
+
+    await vi.waitFor(() =>
+      expect(
+        sent.some(
+          (frame) =>
+            frame.type === 'harness.event' &&
+            frame.event.type === 'CUSTOM' &&
+            frame.event.name === 'harness.operation.finished',
+        ),
+      ).toBe(true),
+    )
+    expect(
+      sent.find((frame) => frame.type === 'harness.receipt'),
+    ).toMatchObject({
+      requestId: 'r1',
+      status: 'accepted',
+    })
+    receive({ type: 'harness.snapshot' })
+    await vi.waitFor(() =>
+      expect(sent.at(-1)).toMatchObject({
+        type: 'harness.snapshot',
+        snapshot: { status: 'idle' },
+      }),
+    )
+    socket.close()
+    await host.close()
+  })
+})
+
+describe('parseControlFrame', () => {
+  it('rejects unknown frames', () => {
+    expect(() => parseControlFrame('{"type":"nope"}')).toThrow('unknown type')
+    expect(() =>
+      parseControlFrame('{"type":"harness.input","requestId":"1","input":{}}'),
+    ).toThrow('Invalid input')
+  })
+})
diff --git a/packages/ai-harness/tests/run-route-hosts.test.ts b/packages/ai-harness/tests/run-route-hosts.test.ts
new file mode 100644
index 0000000000..8bf86d4b59
--- /dev/null
+++ b/packages/ai-harness/tests/run-route-hosts.test.ts
@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHandler, createHarnessHost, defineHarness } from '../src'
+import { gate, mockAdapter, text } from './helpers'
+import type { Reply } from './helpers'
+
+/**
+ * Two server instances over the same stores, with no sticky routing: a run
+ * that starts on host A must be joinable and resumable from host B.
+ */
+function twoHosts() {
+  const { runs, metadata } = memoryPersistence().stores
+  const persistence = { stores: { log: memoryLogStore(), runs, metadata } }
+  const release = gate()
+  // RUN_STARTED, then the rest after `release`. By RUN_STARTED, host A holds
+  // the run lease, so host B only reads.
+  const reply: Reply = () =>
+    (async function* () {
+      const [started, ...rest] = text('Hello from A.')
+      if (started) yield started
+      await release.opened
+      yield* rest
+    })()
+  const { adapter, calls } = mockAdapter([reply])
+  const harness = defineHarness({ name: 'test/run-hosts', adapter })
+  const handlerOf = () => {
+    const host = createHarnessHost({ persistence, coalesceMs: 0 })
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      authorize: (request) => ({
+        id: request.headers.get('x-user') ?? 'user-1',
+      }),
+      canAccess: (principal, threadId) => threadId.startsWith(principal.id),
+      mediaSecret: 'shared',
+    })
+    const call = (path: string, init: RequestInit = {}) =>
+      handler(new Request(`http://h.test/api/${path}`, init))
+    return { host, call }
+  }
+  const a = handlerOf()
+  const b = handlerOf()
+  const post = (on: typeof a, headers: Record<string, string> = {}) =>
+    on.call('run', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...headers },
+      body: JSON.stringify({
+        threadId: 'user-1-t',
+        runId: 'run-a',
+        messages: [{ id: 'm-1', role: 'user', content: 'Hi.' }],
+        tools: [],
+        context: [],
+      }),
+    })
+  const close = () => Promise.all([a.host.close(), b.host.close()])
+  return { a, b, post, release, calls, close }
+}
+
+/** SSE events with their `id:` lines. */
+const withIds = (body: string) =>
+  body
+    .split('\n\n')
+    .filter((block) => block.includes('data: '))
+    .map((block) => ({
+      id: /^id: (.*)$/m.exec(block)?.[1],
+      chunk: JSON.parse(/^data: (.*)$/m.exec(block)?.[1] ?? 'null') as {
+        type: string
+        name?: string
+        delta?: string
+      },
+    }))
+
+/** Read `response` until RUN_STARTED, then cancel it: a cut connection. */
+async function readThenCut(response: Response) {
+  const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader()
+  let body = ''
+  while (!body.includes('RUN_STARTED') || !body.endsWith('\n\n')) {
+    const { value, done } = await reader.read()
+    if (done) break
+    body += value
+  }
+  await reader.cancel()
+  return withIds(body)
+}
+
+describe('a run on a durable host, across instances', () => {
+  it('sends the log cursor as the id of each POST run event', async () => {
+    const { a, post, release, close } = twoHosts()
+    release.open()
+    const events = withIds(await (await post(a)).text())
+    expect(events.length).toBeGreaterThan(3)
+    expect(events.every((event) => /^\d+$/.test(event.id ?? ''))).toBe(true)
+    await close()
+  })
+
+  it('joins a run that host A runs from host B, live, from the start', async () => {
+    const { a, b, post, release, close } = twoHosts()
+    const started = await readThenCut(await post(a))
+    expect(started.at(-1)?.chunk.type).toBe('RUN_STARTED')
+
+    const joined = await b.call('run?runId=run-a&offset=-1')
+    expect(joined.status).toBe(200)
+    release.open()
+    const events = withIds(await joined.text())
+    // The same events, from the start of the turn, as host A sent.
+    expect(events.slice(0, started.length)).toEqual(started)
+    expect(events.some((event) => event.chunk.delta === 'Hello from A.')).toBe(
+      true,
+    )
+    expect(events.at(-1)?.chunk.name).toBe('harness.operation.finished')
+    expect(events.every((event) => event.id !== undefined)).toBe(true)
+    await close()
+  })
+
+  it('resumes a cut join on host B after Last-Event-ID, with no repeated event', async () => {
+    const { a, b, post, release, close } = twoHosts()
+    release.open()
+    const all = withIds(await (await post(a)).text())
+    const cut = all[1]?.id
+    if (cut === undefined) throw new Error('Too few events.')
+
+    const resumed = await b.call('run?runId=run-a', {
+      headers: { 'Last-Event-ID': cut },
+    })
+    const got = withIds(await resumed.text())
+    // Every event after the cut, once, to the end of the turn.
+    expect(got.slice(0, all.length - 2)).toEqual(all.slice(2))
+    expect(got.at(-1)?.chunk.name).toBe('harness.operation.finished')
+    await close()
+  })
+
+  it('resumes a cut POST run on host B: the retry streams from Last-Event-ID and runs nothing again', async () => {
+    const { a, b, post, release, calls, close } = twoHosts()
+    const first = await readThenCut(await post(a))
+    const cut = first.at(-1)?.id
+    if (cut === undefined) throw new Error('No cursor on the first event.')
+
+    // The client re-sends the same POST with the last cursor it saw.
+    const retried = post(b, { 'Last-Event-ID': cut })
+    release.open()
+    const rest = withIds(await (await retried).text())
+    expect(rest[0]?.chunk.type).not.toBe('RUN_STARTED')
+    expect(rest.some((event) => event.chunk.delta === 'Hello from A.')).toBe(
+      true,
+    )
+    expect(rest.at(-1)?.chunk.name).toBe('harness.operation.finished')
+    expect(rest.every((event) => Number(event.id) > Number(cut))).toBe(true)
+    expect(calls).toHaveLength(1)
+    await close()
+  })
+
+  it('shows the run as activeRun on host B, so a reloaded client joins it', async () => {
+    const { a, b, post, release, close } = twoHosts()
+    const posted = await post(a)
+    await readThenCut(posted)
+    const hydrated = await (await b.call('run?threadId=user-1-t')).json()
+    expect(hydrated.activeRun).toEqual({ runId: 'run-a' })
+    release.open()
+    await (await b.call('run?runId=run-a&offset=-1')).text()
+    await close()
+  })
+
+  it('refuses a join on host B of a thread the principal may not use, and 404s an unknown run', async () => {
+    const { a, b, post, release, close } = twoHosts()
+    await readThenCut(await post(a))
+    const refused = await b.call('run?runId=run-a', {
+      headers: { 'x-user': 'user-2' },
+    })
+    expect(refused.status).toBe(403)
+    expect((await b.call('run?runId=nope&offset=-1')).status).toBe(404)
+    release.open()
+    await (await b.call('run?runId=run-a&offset=-1')).text()
+    await close()
+  })
+})
diff --git a/packages/ai-harness/tests/run-route.test.ts b/packages/ai-harness/tests/run-route.test.ts
new file mode 100644
index 0000000000..a930c69d28
--- /dev/null
+++ b/packages/ai-harness/tests/run-route.test.ts
@@ -0,0 +1,614 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { readInterruptBinding, toolDefinition } from '@tanstack/ai'
+import { fakeText } from '@tanstack/ai/testing'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHandler,
+  createHarnessHost,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import { after, gate, mockAdapter, text, toolCall } from './helpers'
+import type { Interrupt } from '@tanstack/ai'
+import type { FakeResponse } from '@tanstack/ai/testing'
+import type { AnyHarness } from '../src'
+
+type Chunk = {
+  type: string
+  runId?: string
+  parentRunId?: string
+  name?: string
+  value?: any
+  delta?: string
+  outcome?: { type: string; interrupts?: Array<Interrupt> }
+}
+
+const deployed: Array<string> = []
+const deploy = toolDefinition({
+  name: 'deploy',
+  description: 'Deploy. Needs approval.',
+  needsApproval: true,
+  inputSchema: z.object({ env: z.string() }),
+}).server(async ({ env }) => {
+  deployed.push(env)
+  return { ok: true }
+})
+
+function setup(
+  harness: AnyHarness,
+  canAccess: () => boolean = () => true,
+  persistence = memoryPersistence(),
+) {
+  const host = createHarnessHost({ persistence })
+  const handler = createHarnessHandler({
+    host,
+    harness,
+    authorize: () => ({ id: 'user-1' }),
+    canAccess,
+  })
+  const call = (path: string, body?: object) =>
+    handler(
+      new Request(`http://h.test/api/${path}`, {
+        ...(body
+          ? {
+              method: 'POST',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify(body),
+            }
+          : {}),
+      }),
+    )
+  const get = (path: string, headers: Record<string, string>) =>
+    handler(new Request(`http://h.test/api/${path}`, { headers }))
+  const run = (body: object) =>
+    call('run', {
+      threadId: 't-1',
+      messages: [],
+      tools: [],
+      context: [],
+      ...body,
+    })
+  return { host, call, get, run }
+}
+
+const sse = (body: string): Array<Chunk> =>
+  body
+    .split('\n\n')
+    .filter((block) => block.startsWith('data: '))
+    .map((block) => JSON.parse(block.slice('data: '.length)))
+
+function approvalHarness(responses: Array<FakeResponse>) {
+  const fake = fakeText()
+  fake.setResponses(responses)
+  return defineHarness({
+    name: 'test/run-route',
+    adapter: fake,
+    tools: [deploy],
+  })
+}
+
+describe('POST run', () => {
+  it('runs the turn as the request runId, so a client can resolve its interrupt', async () => {
+    deployed.length = 0
+    const { host, run } = setup(
+      approvalHarness([
+        { toolCalls: [{ name: 'deploy', input: { env: 'prod' } }] },
+        { text: 'Deployed.' },
+      ]),
+    )
+    const first = sse(
+      await (
+        await run({
+          runId: 'run-a',
+          messages: [{ id: 'm-1', role: 'user', content: 'Deploy.' }],
+        })
+      ).text(),
+    )
+    expect(first.find((chunk) => chunk.type === 'RUN_STARTED')?.runId).toBe(
+      'run-a',
+    )
+    const finished = first.find((chunk) => chunk.type === 'RUN_FINISHED')
+    const interrupt = finished?.outcome?.interrupts?.[0]
+    if (!interrupt) throw new Error('The turn did not stop for the approval.')
+    // ChatClient matches the interrupt against the runId it sent.
+    expect(readInterruptBinding(interrupt)?.interruptedRunId).toBe('run-a')
+
+    const second = await run({
+      runId: 'run-b',
+      parentRunId: 'run-a',
+      resume: [
+        {
+          interruptId: interrupt.id,
+          status: 'resolved',
+          payload: { approved: true },
+        },
+      ],
+    })
+    expect(second.status).toBe(200)
+    const resumed = sse(await second.text())
+    expect(resumed.find((chunk) => chunk.type === 'RUN_STARTED')).toMatchObject(
+      { runId: 'run-b', parentRunId: 'run-a' },
+    )
+    expect(resumed.some((chunk) => chunk.type === 'TOOL_CALL_RESULT')).toBe(
+      true,
+    )
+    expect(deployed).toEqual(['prod'])
+    await host.close()
+  })
+
+  it('runs a repeated request with the same runId once, and refuses that runId for another message', async () => {
+    const { adapter, calls } = mockAdapter([() => text('hello')])
+    const { host, run } = setup(
+      defineHarness({ name: 'test/run-route', adapter }),
+    )
+    const body = {
+      runId: 'run-a',
+      messages: [{ id: 'm-1', role: 'user', content: 'Hi.' }],
+    }
+    expect(await (await run(body)).text()).toContain('"delta":"hello"')
+    expect(await (await run(body)).text()).toContain('"delta":"hello"')
+    expect(calls).toHaveLength(1)
+
+    const other = await run({
+      runId: 'run-a',
+      messages: [{ id: 'm-2', role: 'user', content: 'Something else.' }],
+    })
+    expect(other.status).toBe(409)
+    expect(await other.json()).toEqual({ error: 'conflict' })
+    expect(calls).toHaveLength(1)
+    await host.close()
+  })
+
+  it('refuses a runId that a stored run already has, and leaves that run alone', async () => {
+    const persistence = memoryPersistence()
+    const { runs } = persistence.stores
+    await runs.createOrResume({
+      runId: 'run-x',
+      threadId: 'other',
+      startedAt: 1,
+    })
+    const stored = await runs.get('run-x')
+    const { adapter, calls } = mockAdapter([() => text('hello')])
+    const { host, run } = setup(
+      defineHarness({ name: 'test/run-route', adapter }),
+      undefined,
+      persistence,
+    )
+
+    const response = await run({
+      runId: 'run-x',
+      messages: [{ id: 'm-1', role: 'user', content: 'Hi.' }],
+    })
+    expect(response.status).toBe(409)
+    expect(await response.json()).toEqual({ error: 'conflict' })
+    expect(calls).toHaveLength(0)
+    expect(await runs.get('run-x')).toEqual(stored)
+    await host.close()
+  })
+
+  it('refuses a resume whose runId a stored run already has, and keeps the interrupt', async () => {
+    deployed.length = 0
+    const persistence = memoryPersistence()
+    const { runs } = persistence.stores
+    await runs.createOrResume({
+      runId: 'run-x',
+      threadId: 'other',
+      startedAt: 1,
+    })
+    const stored = await runs.get('run-x')
+    const { host, run } = setup(
+      approvalHarness([
+        { toolCalls: [{ name: 'deploy', input: { env: 'prod' } }] },
+        { text: 'Deployed.' },
+      ]),
+      undefined,
+      persistence,
+    )
+    const first = sse(
+      await (
+        await run({
+          runId: 'run-a',
+          messages: [{ id: 'm-1', role: 'user', content: 'Deploy.' }],
+        })
+      ).text(),
+    )
+    const interrupt = first.find((chunk) => chunk.type === 'RUN_FINISHED')
+      ?.outcome?.interrupts?.[0]
+    if (!interrupt) throw new Error('The turn did not stop for the approval.')
+
+    const resume = [
+      { interruptId: interrupt.id, status: 'resolved', payload: true },
+    ]
+    const refused = await run({ runId: 'run-x', resume })
+    expect(refused.status).toBe(409)
+    expect(await runs.get('run-x')).toEqual(stored)
+    expect(deployed).toEqual([])
+    const session = await host.open(approvalHarness([]), { threadId: 't-1' })
+    expect(session.snapshot().pendingInterrupts).toHaveLength(1)
+    await host.close()
+  })
+
+  it("refuses another person's request with the same runId, and gives them no stream", async () => {
+    const { adapter, calls } = mockAdapter([() => text('hello')])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const handler = createHarnessHandler({
+      host,
+      harness: defineHarness({ name: 'test/run-route', adapter }),
+      canAccess: () => true,
+      authorize: (request) => ({ id: request.headers.get('x-user') ?? '' }),
+    })
+    const post = (user: string) =>
+      handler(
+        new Request('http://h.test/api/run', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', 'x-user': user },
+          body: JSON.stringify({
+            threadId: 't-1',
+            runId: 'r1',
+            messages: [{ id: 'm-1', role: 'user', content: 'Hi.' }],
+            tools: [],
+            context: [],
+          }),
+        }),
+      )
+
+    expect(await (await post('alice')).text()).toContain('"delta":"hello"')
+    const bobs = await post('bob')
+    expect(bobs.status).toBe(409)
+    expect(await bobs.json()).toEqual({ error: 'conflict' })
+    // Alice's retry is still her own input.
+    expect(await (await post('alice')).text()).toContain('"delta":"hello"')
+    expect(calls).toHaveLength(1)
+    await host.close()
+  })
+})
+
+describe('GET run', () => {
+  it('answers the hydrate request of a ChatClient with the transcript and the pending interrupts', async () => {
+    const { host, run, call } = setup(
+      approvalHarness([
+        {
+          text: 'Deploying.',
+          toolCalls: [{ name: 'deploy', input: { env: 'prod' } }],
+        },
+      ]),
+    )
+    const first = sse(
+      await (
+        await run({
+          runId: 'run-a',
+          messages: [{ id: 'm-1', role: 'user', content: 'Deploy.' }],
+        })
+      ).text(),
+    )
+    const interruptId = first.find((chunk) => chunk.type === 'RUN_FINISHED')
+      ?.outcome?.interrupts?.[0]?.id
+
+    const response = await call('run?threadId=t-1')
+    expect(response.status).toBe(200)
+    const body = await response.json()
+    expect(body.messages.map((message: any) => message.role)).toEqual([
+      'user',
+      'assistant',
+    ])
+    expect(body.activeRun).toBeNull()
+    expect(body.interrupts).toMatchObject({
+      runId: 'run-a',
+      pending: [{ id: interruptId }],
+    })
+    await host.close()
+  })
+
+  it('answers an empty thread with no messages and no interrupts', async () => {
+    const { adapter } = mockAdapter([])
+    const { host, call } = setup(
+      defineHarness({ name: 'test/run-route', adapter }),
+    )
+    expect(await (await call('run?threadId=t-1')).json()).toEqual({
+      messages: [],
+      activeRun: null,
+      interrupts: null,
+    })
+    await host.close()
+  })
+
+  it('checks canAccess', async () => {
+    const { adapter } = mockAdapter([])
+    const { host, call } = setup(
+      defineHarness({ name: 'test/run-route', adapter }),
+      () => false,
+    )
+    expect((await call('run?threadId=t-1')).status).toBe(403)
+    await host.close()
+  })
+})
+
+describe('questions', () => {
+  it('sends a question that a tool asks on the POST run stream of its turn', async () => {
+    const probe = toolDefinition({
+      name: 'probe',
+      description: 'Asks a question.',
+      inputSchema: z.object({}),
+    })
+    const plugin = definePlugin({
+      name: 'test/probe',
+      setup: (ctx) => ({
+        tools: [
+          probe.server(async () => ({
+            name: await ctx.session.ask({
+              message: 'What is your name?',
+              schema: z.string(),
+            }),
+          })),
+        ],
+      }),
+    })
+    const { adapter } = mockAdapter([
+      () => toolCall('probe', {}),
+      () => text('Done.'),
+    ])
+    const { host, run, call } = setup(
+      defineHarness({
+        name: 'test/run-route',
+        adapter,
+        plugins: () => [plugin],
+      }),
+    )
+    const response = await run({
+      runId: 'run-a',
+      messages: [{ id: 'm-1', role: 'user', content: 'Go.' }],
+    })
+    const reader = response
+      .body!.pipeThrough(new TextDecoderStream())
+      .getReader()
+    let streamed = ''
+    while (!streamed.includes('harness.question')) {
+      const { value, done } = await reader.read()
+      if (done) throw new Error('The stream ended before the question.')
+      streamed += value
+    }
+    const question = sse(`${streamed}\n\n`).find(
+      (chunk) => chunk.name === 'harness.question',
+    )
+    expect(question?.value).toMatchObject({ message: 'What is your name?' })
+
+    const receipt = await call('control', {
+      threadId: 't-1',
+      input: {
+        op: 'answer',
+        questionId: question?.value.questionId,
+        value: 'Otto',
+      },
+    })
+    expect(await receipt.json()).toMatchObject({ status: 'accepted' })
+    for (;;) {
+      const { value, done } = await reader.read()
+      if (done) break
+      streamed += value
+    }
+    expect(streamed).toContain('Otto')
+    expect(streamed).toContain('harness.question.answered')
+    expect(streamed).toContain('harness.operation.finished')
+
+    // The session stream has the question once.
+    const session = await host.open(
+      defineHarness({ name: 'test/run-route', adapter }),
+      { threadId: 't-1' },
+    )
+    let questions = 0
+    for await (const entry of session.events({
+      signal: AbortSignal.timeout(200),
+    })) {
+      if (
+        entry.event.type === 'CUSTOM' &&
+        entry.event.name === 'harness.question'
+      )
+        questions += 1
+    }
+    expect(questions).toBe(1)
+    await host.close()
+  })
+})
+
+describe('join a running turn', () => {
+  /** A turn whose tool waits for an answer, so it stays running. */
+  function askingHarness() {
+    const probe = toolDefinition({
+      name: 'probe',
+      description: 'Asks a question.',
+      inputSchema: z.object({}),
+    })
+    const plugin = definePlugin({
+      name: 'test/probe',
+      setup: (ctx) => ({
+        tools: [
+          probe.server(async () => ({
+            name: await ctx.session.ask({
+              message: 'Name?',
+              schema: z.string(),
+            }),
+          })),
+        ],
+      }),
+    })
+    const { adapter } = mockAdapter([
+      () => toolCall('probe', {}),
+      () => text('Done.'),
+    ])
+    return defineHarness({
+      name: 'test/run-route',
+      adapter,
+      plugins: () => [plugin],
+    })
+  }
+
+  /** SSE events with their `id:` lines. */
+  const withIds = (body: string) =>
+    body
+      .split('\n\n')
+      .filter((block) => block.includes('data: '))
+      .map((block) => {
+        const id = /^id: (.*)$/m.exec(block)?.[1]
+        const data = /^data: (.*)$/m.exec(block)?.[1] ?? 'null'
+        const chunk: Chunk = JSON.parse(data)
+        return { id, chunk }
+      })
+
+  /** Read `response` until `name` arrives. Returns the reader and the text so far. */
+  async function readUntil(response: Response, name: string) {
+    const reader = response
+      .body!.pipeThrough(new TextDecoderStream())
+      .getReader()
+    let text = ''
+    while (!text.includes(name)) {
+      const { value, done } = await reader.read()
+      if (done) throw new Error(`The stream ended before ${name}.`)
+      text += value
+    }
+    const rest = async () => {
+      for (;;) {
+        const { value, done } = await reader.read()
+        if (done) return text
+        text += value
+      }
+    }
+    return { text, rest }
+  }
+
+  /** Start a turn as `run-a` and wait until its tool asks. */
+  async function startAsking(canAccess?: () => boolean) {
+    const route = setup(askingHarness(), canAccess)
+    const posted = await readUntil(
+      await route.run({
+        runId: 'run-a',
+        messages: [{ id: 'm-1', role: 'user', content: 'Go.' }],
+      }),
+      'harness.question',
+    )
+    const questionId = sse(`${posted.text}\n\n`).find(
+      (chunk) => chunk.name === 'harness.question',
+    )?.value.questionId
+    const answer = () =>
+      route.call('control', {
+        threadId: 't-1',
+        input: { op: 'answer', questionId, value: 'Otto' },
+      })
+    return { ...route, posted, answer }
+  }
+
+  it('shows the running turn as activeRun in the hydrate answer', async () => {
+    const { host, call, answer, posted } = await startAsking()
+    const running = await (await call('run?threadId=t-1')).json()
+    expect(running.activeRun).toEqual({ runId: 'run-a' })
+
+    await answer()
+    await posted.rest()
+    const ended = await (await call('run?threadId=t-1')).json()
+    expect(ended.activeRun).toBeNull()
+    await host.close()
+  })
+
+  it('streams the turn from its start to its end, as POST run does', async () => {
+    const { host, call, answer, posted } = await startAsking()
+    const joined = await call('run?runId=run-a&offset=-1')
+    expect(joined.status).toBe(200)
+    expect(joined.headers.get('content-type')).toContain('text/event-stream')
+    const reading = await readUntil(joined, 'harness.question')
+
+    await answer()
+    const [postedText, joinedText] = await Promise.all([
+      posted.rest(),
+      reading.rest(),
+    ])
+    const events = withIds(joinedText)
+    expect(events.every((event) => event.id !== undefined)).toBe(true)
+    expect(events.some((event) => event.chunk.type === 'RUN_STARTED')).toBe(
+      true,
+    )
+    expect(joinedText).toContain('Done.')
+    expect(joinedText).toContain('harness.operation.finished')
+    // The same events as the stream that started the turn.
+    expect(events.map((event) => event.chunk)).toEqual(sse(postedText))
+    await host.close()
+  })
+
+  it('resumes after Last-Event-ID with no repeated event, also after the turn ended', async () => {
+    const { host, call, get, answer, posted } = await startAsking()
+    await answer()
+    await posted.rest()
+    const all = withIds(await (await call('run?runId=run-a&offset=-1')).text())
+    expect(all.at(-1)?.chunk.name).toBe('harness.operation.finished')
+    const cut = all[2]?.id
+    if (cut === undefined) throw new Error('Too few events.')
+
+    const resumed = await get('run?offset=-1', {
+      'X-Run-Id': 'run-a',
+      'Last-Event-ID': cut,
+    })
+    expect(withIds(await resumed.text())).toEqual(all.slice(3))
+    await host.close()
+  })
+
+  it('refuses a join of a thread the principal may not use', async () => {
+    let allowed = true
+    const { host, call, answer, posted } = await startAsking(() => allowed)
+    allowed = false
+    expect((await call('run?runId=run-a')).status).toBe(403)
+    allowed = true
+    await answer()
+    await posted.rest()
+    await host.close()
+  })
+
+  it('answers 404 for a run this host does not run', async () => {
+    const { adapter } = mockAdapter([])
+    const { host, call } = setup(
+      defineHarness({ name: 'test/run-route', adapter }),
+    )
+    const response = await call('run?runId=nope&offset=-1')
+    expect(response.status).toBe(404)
+    expect(await response.json()).toEqual({ error: 'unknown run' })
+    await host.close()
+  })
+})
+
+describe('snapshot', () => {
+  it('gives each running operation the cursor its events start after', async () => {
+    const held = gate()
+    const { adapter } = mockAdapter([
+      () => text('Warm.'),
+      after(held.opened, 'First.'),
+    ])
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({ name: 'test/run-route', adapter }),
+      { threadId: 't-1' },
+    )
+    // Events of another turn come before this one.
+    await session.prompt('Warm up.')
+    const turn = session.prompt('Start.')
+    await turn.receipt
+    const [active] = session.snapshot().activeOperations
+    expect(active?.id).toBe(turn.id)
+    const startedCursor = active?.startedCursor
+    if (startedCursor === undefined) throw new Error('No start cursor.')
+
+    held.open()
+    await turn
+    const ofTurn = async (from?: string) => {
+      const ids: Array<string> = []
+      for await (const entry of session.events({
+        ...(from ? { from } : {}),
+        signal: AbortSignal.timeout(200),
+      })) {
+        if (entry.operationId === turn.id) ids.push(entry.cursor)
+      }
+      return ids
+    }
+    const all = await ofTurn()
+    expect(all.length).toBeGreaterThan(0)
+    expect(await ofTurn(startedCursor)).toEqual(all)
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/transport-edges.test.ts b/packages/ai-harness/tests/transport-edges.test.ts
new file mode 100644
index 0000000000..48ae11d058
--- /dev/null
+++ b/packages/ai-harness/tests/transport-edges.test.ts
@@ -0,0 +1,632 @@
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { defineAgent, toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  applyInput,
+  capabilitiesOf,
+  createHarnessHandler,
+  createHarnessHost,
+  defineHarness,
+  handleHarnessSocket,
+  parseControlFrame,
+  parseHarnessInput,
+} from '../src'
+import { createHarnessClient } from '../src/client'
+import { gate, mockAdapter, text, toolCall, untilAborted } from './helpers'
+import type { WebSocketLike } from '@tanstack/ai'
+import type { HostFrame } from '../src'
+
+const pricer = defineAgent({
+  name: 'pricer',
+  description: 'Prices a vendor',
+  produces: 'data',
+  inputSchema: z.object({ vendor: z.string() }),
+  run: async (ctx) => ({ cents: ctx.input.vendor.length }),
+})
+const lookup = toolDefinition({
+  name: 'lookup',
+  description: 'Look up a fact',
+  inputSchema: z.object({ q: z.string() }),
+}).server(async () => 'found')
+const remove = toolDefinition({
+  name: 'remove',
+  description: 'Remove a file',
+  needsApproval: true,
+  inputSchema: z.object({ path: z.string() }),
+}).server(async () => ({ removed: true }))
+
+const auth = { authorization: 'Bearer good' }
+
+function setup(replies: Parameters<typeof mockAdapter>[0] = []) {
+  const { adapter, calls } = mockAdapter(replies)
+  const harness = defineHarness({
+    name: 'test/transport',
+    adapter,
+    tools: [lookup, remove],
+    agents: [pricer],
+    subagents: { agents: [pricer] },
+    expose: { agents: ['pricer'] },
+  })
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const handler = createHarnessHandler({
+    host,
+    harness,
+    authorize: (request) =>
+      request.headers.get('authorization') === 'Bearer good'
+        ? { id: 'user-1' }
+        : null,
+    canAccess: (principal, threadId) => threadId.startsWith(principal.id),
+  })
+  const call = (path: string, init: RequestInit = {}) =>
+    handler(
+      new Request(`http://x/api/harness/${path}`, {
+        ...init,
+        headers: {
+          ...auth,
+          'content-type': 'application/json',
+          ...init.headers,
+        },
+      }),
+    )
+  return { handler, host, harness, calls, call }
+}
+
+const runBody = (threadId: string, extra: Record<string, unknown> = {}) =>
+  JSON.stringify({
+    threadId,
+    runId: 'client-run',
+    messages: [],
+    tools: [],
+    context: [],
+    state: {},
+    forwardedProps: {},
+    ...extra,
+  })
+
+describe('HTTP handler edges', () => {
+  it('answers bad requests with 400, 403, and 404', async () => {
+    const { host, call } = setup()
+    const statusOf = async (path: string, init?: RequestInit) =>
+      (await call(path, init)).status
+
+    expect(await statusOf('events')).toBe(400)
+    expect(await statusOf('events?threadId=someone-else')).toBe(403)
+    expect(await statusOf('snapshot')).toBe(400)
+    expect(await statusOf('nowhere')).toBe(404)
+    expect(await statusOf('run', { method: 'GET' })).toBe(400)
+
+    const control = (body: string) =>
+      statusOf('control', { method: 'POST', body })
+    expect(await control('null')).toBe(400)
+    expect(await control('{"input":{}}')).toBe(400)
+    expect(await control('{"threadId":7}')).toBe(400)
+    expect(await control('{"threadId":"user-1-a"}')).toBe(400)
+    expect(await control('not json')).toBe(400)
+    expect(
+      await control(
+        '{"threadId":"someone-else","input":{"op":"prompt","message":"hi"}}',
+      ),
+    ).toBe(403)
+
+    expect(
+      await statusOf('run', { method: 'POST', body: runBody('someone-else') }),
+    ).toBe(403)
+    const noMessage = await call('run', {
+      method: 'POST',
+      body: runBody('user-1-r', {
+        messages: [{ id: 'a', role: 'assistant', content: 'hello' }],
+      }),
+    })
+    expect(noMessage.status).toBe(400)
+    expect(await noMessage.json()).toEqual({ error: 'no user message' })
+    await host.close()
+  })
+
+  it('reads the prompt from AG-UI content parts', async () => {
+    const { host, call, calls } = setup([() => text('from parts')])
+    const response = await call('run', {
+      method: 'POST',
+      body: runBody('user-1-parts', {
+        messages: [
+          {
+            id: 'u1',
+            role: 'user',
+            content: [
+              { type: 'text', text: 'part one, ' },
+              { type: 'binary', mimeType: 'image/png', data: 'AA==' },
+              { type: 'text', text: 'part two' },
+            ],
+          },
+        ],
+      }),
+    })
+    expect(await response.text()).toContain('from parts')
+    expect(JSON.stringify(calls[0].messages)).toContain('part one, part two')
+    await host.close()
+  })
+
+  it('continues an interrupted turn when a run request carries resume', async () => {
+    const { host, call } = setup([
+      () => toolCall('remove', { path: 'a.txt' }),
+      () => text('removed it'),
+    ])
+    const control = await call('control', {
+      method: 'POST',
+      body: JSON.stringify({
+        threadId: 'user-1-resume',
+        input: { op: 'prompt', message: 'remove a.txt' },
+      }),
+    })
+    expect((await control.json()).status).toBe('accepted')
+    const snapshotOf = async () =>
+      (await call('snapshot?threadId=user-1-resume')).json()
+    await vi.waitFor(async () =>
+      expect((await snapshotOf()).status).toBe('requires_action'),
+    )
+    const [interrupt] = (await snapshotOf()).pendingInterrupts
+
+    // A thread with no stopped turn has nothing to resume.
+    const nothing = await call('run', {
+      method: 'POST',
+      body: runBody('user-1-idle', {
+        resume: [{ interruptId: 'nope', status: 'resolved', payload: true }],
+      }),
+    })
+    expect(nothing.status).toBe(409)
+
+    // Each AG-UI request has its own runId.
+    const resumed = await call('run', {
+      method: 'POST',
+      body: runBody('user-1-resume', {
+        runId: 'client-run-2',
+        resume: [
+          { interruptId: interrupt.id, status: 'resolved', payload: true },
+        ],
+      }),
+    })
+    expect(resumed.headers.get('content-type')).toContain('text/event-stream')
+    const body = await resumed.text()
+    expect(body).toContain('removed it')
+    expect(body).toContain('harness.operation.finished')
+    await host.close()
+  })
+
+  it('streams session events from a `from` query cursor', async () => {
+    const { host, call } = setup([() => text('one'), () => text('two')])
+    const prompt = (message: string) =>
+      call('control', {
+        method: 'POST',
+        body: JSON.stringify({
+          threadId: 'user-1-from',
+          input: { op: 'prompt', message },
+        }),
+      })
+    await prompt('first')
+    await vi.waitFor(async () =>
+      expect(
+        (await (await call('snapshot?threadId=user-1-from')).json()).status,
+      ).toBe('idle'),
+    )
+    const snapshot = await (await call('snapshot?threadId=user-1-from')).json()
+    await prompt('second')
+    const response = await call(
+      `events?threadId=user-1-from&from=${snapshot.cursor}`,
+    )
+    const reader = response.body!.getReader()
+    let seen = ''
+    while (!seen.includes('harness.operation.finished')) {
+      const { value, done } = await reader.read()
+      if (done) break
+      seen += new TextDecoder().decode(value)
+    }
+    await reader.cancel()
+    expect(seen).toContain('two')
+    expect(seen).not.toContain('"delta":"one"')
+    await host.close()
+  })
+})
+
+describe('WebSocket edges', () => {
+  function fakeSocket(options: { failSend?: boolean } = {}) {
+    const handlers: Record<string, Array<(event?: any) => void>> = {}
+    const sent: Array<HostFrame> = []
+    const closed: Array<number | undefined> = []
+    const socket: WebSocketLike = {
+      send: (data) => {
+        if (options.failSend) throw new Error('socket gone')
+        sent.push(JSON.parse(data))
+      },
+      close: (code?: number) => {
+        closed.push(code)
+        handlers.close?.forEach((handler) => handler())
+      },
+      addEventListener: (type: string, handler: (event?: any) => void) => {
+        ;(handlers[type] ??= []).push(handler)
+      },
+    }
+    const receive = (frame: unknown) =>
+      handlers.message?.forEach((handler) =>
+        handler({
+          data: typeof frame === 'string' ? frame : JSON.stringify(frame),
+        }),
+      )
+    const fail = () => handlers.error?.forEach((handler) => handler())
+    return { socket, sent, closed, receive, fail }
+  }
+
+  it('refuses a thread the principal cannot access', async () => {
+    const { host, harness } = setup()
+    const { socket, sent, closed, receive } = fakeSocket()
+    handleHarnessSocket({
+      host,
+      harness,
+      socket,
+      principal: { id: 'user-1' },
+      canAccess: () => false,
+    })
+    receive({ type: 'harness.subscribe', threadId: 'user-1-x' })
+    await vi.waitFor(() => expect(closed).toEqual([4403]))
+    expect(sent).toEqual([{ type: 'harness.error', message: 'forbidden' }])
+    await host.close()
+  })
+
+  it('reports a second subscribe and bad frames, and resumes from a cursor', async () => {
+    const { host, harness } = setup([() => text('hello')])
+    const first = fakeSocket()
+    handleHarnessSocket({
+      host,
+      harness,
+      socket: first.socket,
+      principal: { id: 'user-1' },
+      canAccess: () => true,
+    })
+    first.receive({ type: 'harness.subscribe', threadId: 'user-1-ws2' })
+    await vi.waitFor(() =>
+      expect(first.sent.some((frame) => frame.type === 'harness.hello')).toBe(
+        true,
+      ),
+    )
+    first.receive({ type: 'harness.subscribe', threadId: 'user-1-ws2' })
+    await vi.waitFor(() =>
+      expect(first.sent.at(-1)).toEqual({
+        type: 'harness.error',
+        message: 'Already subscribed.',
+      }),
+    )
+    first.receive('[1, 2]')
+    await vi.waitFor(() =>
+      expect(first.sent.at(-1)).toMatchObject({ type: 'harness.error' }),
+    )
+    first.receive({
+      type: 'harness.input',
+      requestId: 'p1',
+      input: { op: 'prompt', message: 'hi' },
+    })
+    await vi.waitFor(() =>
+      expect(
+        first.sent.some(
+          (frame) =>
+            frame.type === 'harness.event' &&
+            frame.event.type === 'CUSTOM' &&
+            frame.event.name === 'harness.operation.finished',
+        ),
+      ).toBe(true),
+    )
+    const cursor = first.sent
+      .filter((frame) => frame.type === 'harness.event')
+      .at(-1)
+    first.fail()
+
+    // A new socket that resumes after the last cursor sees nothing old.
+    const second = fakeSocket()
+    handleHarnessSocket({
+      host,
+      harness,
+      socket: second.socket,
+      principal: { id: 'user-1' },
+      canAccess: () => true,
+    })
+    second.receive({
+      type: 'harness.subscribe',
+      threadId: 'user-1-ws2',
+      from: cursor && 'cursor' in cursor ? cursor.cursor : undefined,
+    })
+    await vi.waitFor(() =>
+      expect(second.sent.some((frame) => frame.type === 'harness.hello')).toBe(
+        true,
+      ),
+    )
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    expect(
+      second.sent.filter((frame) => frame.type === 'harness.event'),
+    ).toEqual([])
+    second.socket.close()
+    await host.close()
+  })
+
+  it('takes an input sent right after the subscribe, before the hello', async () => {
+    const { host, harness } = setup([() => text('hello')])
+    const { socket, sent, receive } = fakeSocket()
+    handleHarnessSocket({
+      host,
+      harness,
+      socket,
+      principal: { id: 'user-1' },
+      canAccess: () => true,
+    })
+    receive({ type: 'harness.subscribe', threadId: 'user-1-ws3' })
+    receive({
+      type: 'harness.input',
+      requestId: 'p1',
+      input: { op: 'prompt', message: 'hi' },
+    })
+    await vi.waitFor(() =>
+      expect(
+        sent.find((frame) => frame.type === 'harness.receipt'),
+      ).toMatchObject({ requestId: 'p1', status: 'accepted' }),
+    )
+    expect(sent.some((frame) => frame.type === 'harness.error')).toBe(false)
+    socket.close()
+    await host.close()
+  })
+
+  it('stops reading when the socket cannot send', async () => {
+    const { host, harness } = setup()
+    const { socket, receive } = fakeSocket({ failSend: true })
+    handleHarnessSocket({
+      host,
+      harness,
+      socket,
+      principal: { id: 'user-1' },
+      canAccess: () => true,
+    })
+    receive({ type: 'harness.subscribe', threadId: 'user-1-dead' })
+    // Nothing to assert on the socket: the send failure must not throw.
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    await host.close()
+  })
+})
+
+describe('protocol parsing and inputs', () => {
+  it('checks each input op for its fields', () => {
+    expect(() => parseHarnessInput(null)).toThrow('known op')
+    expect(() => parseHarnessInput({ op: 'launch' })).toThrow('known op')
+    expect(() => parseHarnessInput({ op: 'steer' })).toThrow(
+      'steer needs a message',
+    )
+    expect(() => parseHarnessInput({ op: 'resolve' })).toThrow(
+      'resolve needs a resume array',
+    )
+    expect(() => parseHarnessInput({ op: 'agent' })).toThrow(
+      'agent needs an agent name',
+    )
+    expect(
+      parseHarnessInput({
+        op: 'followUp',
+        message: [{ type: 'text', content: 'x' }],
+      }),
+    ).toMatchObject({ op: 'followUp' })
+    expect(parseHarnessInput({ op: 'cancel' })).toEqual({ op: 'cancel' })
+  })
+
+  it('parses subscribe frames with a cursor and refuses non-objects', () => {
+    expect(
+      parseControlFrame(
+        '{"type":"harness.subscribe","threadId":"t","from":"4"}',
+      ),
+    ).toEqual({ type: 'harness.subscribe', threadId: 't', from: '4' })
+    expect(
+      parseControlFrame('{"type":"harness.subscribe","threadId":"t","from":4}'),
+    ).toEqual({ type: 'harness.subscribe', threadId: 't' })
+    expect(() => parseControlFrame('7')).toThrow('Invalid frame.')
+    expect(() => parseControlFrame('null')).toThrow('Invalid frame.')
+  })
+
+  it('applies steer, follow-up, resolve, cancel, busy prompts, and agents', async () => {
+    const release = gate()
+    const { host, harness } = setup([
+      () =>
+        (async function* () {
+          await release.opened
+          yield* text('slow answer')
+        })(),
+      () => text('queued answer'),
+      () => text('follow-up answer'),
+    ])
+    const session = await host.open(harness, { threadId: 'user-1-apply' })
+
+    const first = await applyInput(harness, session, {
+      op: 'prompt',
+      message: 'slow',
+    })
+    expect(first.status).toBe('accepted')
+    const queued = await applyInput(harness, session, {
+      op: 'prompt',
+      message: 'next',
+      busy: 'queue',
+    })
+    expect(queued.status).toBe('queued')
+    expect(
+      await applyInput(harness, session, { op: 'steer', message: 'faster' }),
+    ).toHaveProperty('status')
+    expect(
+      await applyInput(harness, session, { op: 'followUp', message: 'after' }),
+    ).toHaveProperty('status')
+    release.open()
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('idle'))
+
+    expect(
+      await applyInput(harness, session, { op: 'resolve', resume: [] }),
+    ).toMatchObject({ status: 'rejected' })
+    expect(await applyInput(harness, session, { op: 'cancel' })).toHaveProperty(
+      'status',
+    )
+    // defineHarness refuses this, but a hand-built harness object can name an
+    // exposed agent that the session does not have.
+    const loose = { ...harness, expose: { agents: ['pricer', 'ghost'] } }
+    expect(
+      await applyInput(loose, session, { op: 'agent', agent: 'ghost' }),
+    ).toEqual({ inputId: '', status: 'rejected', reason: 'unknown_agent' })
+    const detached = await applyInput(harness, session, {
+      op: 'agent',
+      agent: 'pricer',
+      input: { vendor: 'acme' },
+      detached: true,
+    })
+    expect(detached).toMatchObject({ status: 'accepted' })
+    await session.operation(detached.operationId ?? '')
+    await host.close()
+  })
+
+  it('describes tools, subagents, and what exposed agents produce', () => {
+    const { harness } = setup()
+    const capabilities = capabilitiesOf(harness)
+    expect(capabilities.tools.items.map((tool) => tool.name)).toEqual([
+      'lookup',
+      'remove',
+    ])
+    expect(capabilities.multiAgent).toMatchObject({
+      supported: true,
+      subagents: [{ name: 'pricer', description: 'Prices a vendor' }],
+    })
+    expect(capabilities.custom.tanstack.agents[0]).toMatchObject({
+      name: 'pricer',
+      produces: 'data',
+    })
+    const bare = capabilitiesOf(
+      defineHarness({ name: 'test/bare', adapter: mockAdapter([]).adapter }),
+    )
+    expect(bare.multiAgent.supported).toBe(false)
+    expect(bare.tools.items).toEqual([])
+  })
+})
+
+describe('createHarnessClient edges', () => {
+  it('sends every input op with headers from a function', async () => {
+    const { host, harness, handler } = setup([
+      () => text('a'),
+      () => text('b'),
+      () => text('c'),
+    ])
+    const seenAuth: Array<string | null> = []
+    const client = createHarnessClient<typeof harness>({
+      url: 'http://x/api/harness',
+      threadId: 'user-1-client',
+      headers: () => auth,
+      fetch: (input, init) => {
+        const request = new Request(input, init)
+        seenAuth.push(request.headers.get('authorization'))
+        return handler(request)
+      },
+    })
+    expect((await client.prompt('hi', { busy: 'queue' })).status).toBe(
+      'accepted',
+    )
+    await client.steer('go on')
+    await client.followUp('then')
+    expect((await client.resolve([])).status).toBe('rejected')
+    await client.cancel()
+    await client.cancel('op-missing')
+    expect(
+      (await client.agents.pricer.start({ vendor: 'x' }, { detached: true }))
+        .status,
+    ).toBe('accepted')
+    expect(seenAuth.every((value) => value === 'Bearer good')).toBe(true)
+    // Symbol keys on the agents proxy are not agents.
+    expect(
+      (client.agents as unknown as Record<symbol, unknown>)[Symbol.iterator],
+    ).toBeUndefined()
+    await host.close()
+  })
+
+  it('reports errors from the handler and a failed snapshot', async () => {
+    const client = createHarnessClient({
+      url: 'http://x/api/harness/',
+      threadId: 't',
+      fetch: async (input) =>
+        String(input).includes('snapshot')
+          ? new Response('nope', { status: 500 })
+          : new Response('"plain"', { status: 502, statusText: 'Bad Gateway' }),
+    })
+    await expect(client.prompt('hi')).rejects.toThrow(
+      'Harness request failed (502): Bad Gateway',
+    )
+    await expect(client.snapshot()).rejects.toThrow(
+      'Harness snapshot failed (500)',
+    )
+  })
+
+  it('reconnects after a failed events request and resumes from the cursor', async () => {
+    const urls: Array<string> = []
+    const frame = (cursor: string) =>
+      `id: ${cursor}\ndata: ${JSON.stringify({
+        type: 'harness.event',
+        cursor,
+        operationId: 'op',
+        event: { type: 'CUSTOM', name: 'tick', value: cursor, timestamp: 1 },
+      })}\n\n`
+    let calls = 0
+    const client = createHarnessClient({
+      url: 'http://x/api/harness',
+      threadId: 't',
+      reconnectDelayMs: 1,
+      fetch: async (input) => {
+        urls.push(String(input))
+        calls += 1
+        if (calls === 1) return new Response('down', { status: 503 })
+        if (calls === 2) throw new Error('network')
+        const body = calls === 3 ? `: comment\n\n${frame('1')}` : frame('2')
+        return new Response(body, { status: 200 })
+      },
+    })
+    const controller = new AbortController()
+    const seen: Array<string> = []
+    for await (const entry of client.events({
+      from: '0',
+      signal: controller.signal,
+    })) {
+      seen.push(entry.cursor)
+      if (seen.length === 2) controller.abort()
+    }
+    expect(seen).toEqual(['1', '2'])
+    expect(urls[0]).toContain('from=0')
+    expect(urls.at(-1)).toContain('from=1')
+  })
+
+  it('stops quietly when aborted during a request', async () => {
+    const controller = new AbortController()
+    const client = createHarnessClient({
+      url: 'http://x/api/harness',
+      threadId: 't',
+      fetch: async () => {
+        controller.abort()
+        throw new Error('aborted')
+      },
+    })
+    const seen: Array<unknown> = []
+    for await (const entry of client.events({ signal: controller.signal })) {
+      seen.push(entry)
+    }
+    expect(seen).toEqual([])
+  })
+})
+
+describe('an operation that waits for cancel', () => {
+  it('cancels through a control input', async () => {
+    const { host, harness } = setup([untilAborted()])
+    const session = await host.open(harness, { threadId: 'user-1-cancel' })
+    const operation = session.prompt('wait')
+    await vi.waitFor(() => expect(session.snapshot().status).toBe('running'))
+    await applyInput(harness, session, {
+      op: 'cancel',
+      operationId: operation.id,
+    })
+    await operation.then(
+      () => undefined,
+      () => undefined,
+    )
+    expect(operation.status()).toBe('cancelled')
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/types.test-d.ts b/packages/ai-harness/tests/types.test-d.ts
index 14b9f17727..b0bcd6596c 100644
--- a/packages/ai-harness/tests/types.test-d.ts
+++ b/packages/ai-harness/tests/types.test-d.ts
@@ -1,7 +1,13 @@
 import { expectTypeOf, it } from 'vitest'
 import { z } from 'zod'
 import { defineAgent } from '@tanstack/ai'
-import { defineHarness, definePlugin } from '../src'
+import {
+  createHarnessHandler,
+  createHarnessHost,
+  defineHarness,
+  definePlugin,
+  oauthConnector,
+} from '../src'
 import { mockAdapter } from './helpers'
 import type { AnyTextAdapter, KeyedAdapter } from '@tanstack/ai'
 import type { SessionIndexEntry } from '@tanstack/ai-persistence'
@@ -158,3 +164,19 @@ it('refuses a plugin whose metadata the harness does not have', () => {
     plugins: () => [other],
   })
 })
+
+it('needs an explicit canAccess and an explicit login mode', () => {
+  const host = createHarnessHost()
+  // @ts-expect-error `canAccess` is required: allow-all must be explicit.
+  createHarnessHandler({ host, harness, authorize: () => ({ id: 'u' }) })
+  createHarnessHandler({
+    host,
+    harness,
+    authorize: () => ({ id: 'u' }),
+    canAccess: () => true,
+  })
+  const oauth = { authorizationUrl: 'a', tokenUrl: 't', clientId: 'c' }
+  // @ts-expect-error `login` is required: no implicit loopback listener.
+  oauthConnector({ id: 'svc', label: 'Service', oauth })
+  oauthConnector({ id: 'svc', label: 'Service', oauth, login: 'device' })
+})
diff --git a/packages/ai-harness/tests/view-client-tools.test.ts b/packages/ai-harness/tests/view-client-tools.test.ts
new file mode 100644
index 0000000000..9522b91806
--- /dev/null
+++ b/packages/ai-harness/tests/view-client-tools.test.ts
@@ -0,0 +1,176 @@
+import { describe, expect, it, vi } from 'vitest'
+import { toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { z } from 'zod'
+import { createHarnessHandler, createHarnessHost, defineHarness } from '../src'
+import { createHarnessClient } from '../src/client'
+import { createSessionView } from '../src/view'
+import { mockAdapter, text, toolCall } from './helpers'
+import type { Reply } from './helpers'
+import type { ClientToolCall } from '../src/view'
+
+// No server implementation: the turn waits for the result from the UI.
+const openScreen = toolDefinition({
+  name: 'openScreen',
+  description: 'Open a screen in the browser.',
+  inputSchema: z.object({ route: z.string() }),
+  outputSchema: z.object({ opened: z.boolean() }),
+})
+const remove = toolDefinition({
+  name: 'remove',
+  description: 'Remove',
+  needsApproval: true,
+}).server(async () => 'removed')
+
+async function open(replies: Array<Reply>) {
+  const main = mockAdapter(replies)
+  const harness = defineHarness({
+    name: 'test/view-client-tools',
+    adapter: main.adapter,
+    tools: [openScreen, remove],
+  })
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  const session = await host.open(harness, { threadId: 't' })
+  return { host, harness, session, calls: main.calls }
+}
+
+/** The tool messages the model got on its last call. */
+const toolResults = (calls: Array<any>) =>
+  (calls.at(-1).messages as Array<any>)
+    .filter((message) => message.role === 'tool')
+    .map((message) => JSON.parse(message.content))
+
+describe('session view client tools', () => {
+  it('lists a client tool apart from approvals and sends its output', async () => {
+    const { host, harness, calls } = await open([
+      () => toolCall('openScreen', { route: '/settings' }, 'c1'),
+      () => text('Opened it.'),
+    ])
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      canAccess: () => true,
+      authorize: () => ({ id: 'u' }),
+    })
+    const controls: Array<unknown> = []
+    const client = createHarnessClient({
+      url: 'http://local/api/harness',
+      threadId: 't',
+      fetch: async (input, init) => {
+        const request = new Request(input, init)
+        if (request.url.endsWith('/control'))
+          controls.push((await request.clone().json()).input)
+        return handler(request)
+      },
+    })
+    const view = createSessionView(client)
+    const asked: Array<ClientToolCall> = []
+    view.on('clientTool', (call) => asked.push(call))
+    await view.ready
+
+    await view.send('Open settings.')
+    await vi.waitFor(() => expect(view.store.get().clientTools).toHaveLength(1))
+    const [call] = view.store.get().clientTools
+    expect(view.store.get().approvals).toEqual([])
+    expect(call).toMatchObject({
+      toolCallId: 'c1',
+      tool: 'openScreen',
+      args: { route: '/settings' },
+    })
+    expect(asked).toEqual([call])
+
+    call?.resolve({ opened: true })
+
+    await vi.waitFor(() =>
+      expect(JSON.stringify(view.store.get().messages)).toContain('Opened it.'),
+    )
+    expect(controls.at(-1)).toEqual({
+      op: 'resolve',
+      resume: [
+        {
+          interruptId: call?.id,
+          status: 'resolved',
+          payload: { opened: true },
+        },
+      ],
+    })
+    expect(calls).toHaveLength(2)
+    expect(toolResults(calls)).toEqual([{ opened: true }])
+    expect(view.store.get().clientTools).toEqual([])
+    view.dispose()
+    await host.close()
+  })
+
+  it('sends one resolve when every approval and client tool has an answer', async () => {
+    const { host, session, calls } = await open([
+      () => [
+        ...toolCall('remove', {}, 'c1').slice(0, -1),
+        ...toolCall('openScreen', { route: '/home' }, 'c2').slice(1),
+      ],
+      () => text('Both done.'),
+    ])
+    const view = createSessionView(session)
+    await view.ready
+    const resolve = vi.spyOn(session, 'resolve')
+
+    await view.send('clean up and go home')
+    await vi.waitFor(() => {
+      expect(view.store.get().approvals).toHaveLength(1)
+      expect(view.store.get().clientTools).toHaveLength(1)
+    })
+    const [approval] = view.store.get().approvals
+    const [call] = view.store.get().clientTools
+    expect(approval?.tool).toBe('remove')
+    expect(call?.tool).toBe('openScreen')
+
+    approval?.approve()
+    // A client tool id is not an approval, so a yes does not answer it.
+    view.approve(call?.id ?? '')
+    expect(resolve).not.toHaveBeenCalled()
+    call?.resolve({ opened: true })
+    call?.resolve({ opened: false })
+
+    expect(resolve).toHaveBeenCalledTimes(1)
+    expect(resolve.mock.calls[0]?.[0]).toEqual([
+      { interruptId: approval?.id, status: 'resolved', payload: true },
+      { interruptId: call?.id, status: 'resolved', payload: { opened: true } },
+    ])
+    await vi.waitFor(() =>
+      expect(JSON.stringify(view.store.get().messages)).toContain('Both done.'),
+    )
+    expect(calls).toHaveLength(2)
+    view.dispose()
+    await host.close()
+  })
+
+  it('sends a failed client tool as an error the model sees', async () => {
+    const { host, session, calls } = await open([
+      () => toolCall('openScreen', { route: '/settings' }, 'c1'),
+      () => text('It failed.'),
+    ])
+    const view = createSessionView(session)
+    await view.ready
+    const resolve = vi.spyOn(session, 'resolve')
+
+    await view.send('Open settings.')
+    await vi.waitFor(() => expect(view.store.get().clientTools).toHaveLength(1))
+    const [call] = view.store.get().clientTools
+    call?.fail('boom')
+
+    expect(resolve.mock.calls[0]?.[0]).toEqual([
+      {
+        interruptId: call?.id,
+        status: 'resolved',
+        payload: { error: 'boom' },
+        metadata: { tanstack: { state: 'output-error' } },
+      },
+    ])
+    await vi.waitFor(() =>
+      expect(JSON.stringify(view.store.get().messages)).toContain('It failed.'),
+    )
+    expect(calls).toHaveLength(2)
+    expect(JSON.stringify(calls[1].messages)).toContain('boom')
+    view.dispose()
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/tests/view-fixtures.ts b/packages/ai-harness/tests/view-fixtures.ts
new file mode 100644
index 0000000000..df0fc47cc1
--- /dev/null
+++ b/packages/ai-harness/tests/view-fixtures.ts
@@ -0,0 +1,60 @@
+import { EventType } from '@tanstack/ai'
+import { emptyUsage } from '../src/usage'
+import type { StreamChunk } from '@tanstack/ai'
+import type { SessionEvent, SessionSnapshot } from '../src'
+
+let cursor = 0
+
+/** A session event with the next cursor. */
+export function at(event: StreamChunk, operationId = 'op-1'): SessionEvent {
+  cursor += 1
+  return { cursor: String(cursor), operationId, event }
+}
+
+/** A `CUSTOM` event that the session itself sends. */
+export function custom(name: string, value: unknown) {
+  return at({ type: EventType.CUSTOM, name, value }, 'session')
+}
+
+/**
+ * Run events of a child agent. At runtime they carry `subagentRunId`, but the
+ * RUN_* event types do not list it. So they are values here, not object
+ * literals at the call site.
+ */
+export const childRun = {
+  started: {
+    type: EventType.RUN_STARTED,
+    threadId: 't',
+    runId: 'r:child-1',
+    subagentRunId: 'child-1',
+  },
+  finished: {
+    type: EventType.RUN_FINISHED,
+    threadId: 't',
+    runId: 'r:child-1',
+    subagentRunId: 'child-1',
+  },
+  error: {
+    type: EventType.RUN_ERROR,
+    message: 'child broke',
+    subagentRunId: 'child-1',
+  },
+} as const
+
+/** An idle session snapshot with nothing pending, and `over` on top. */
+export function sessionSnapshot(
+  over: Partial<SessionSnapshot> = {},
+): SessionSnapshot {
+  return {
+    threadId: 't',
+    status: 'idle',
+    activeOperations: [],
+    queuedTurns: 0,
+    pendingInterrupts: [],
+    pendingQuestions: [],
+    plugins: {},
+    usage: emptyUsage(),
+    cursor: '0',
+    ...over,
+  }
+}
diff --git a/packages/ai-harness/tests/view-media.test.ts b/packages/ai-harness/tests/view-media.test.ts
new file mode 100644
index 0000000000..08ccb9c572
--- /dev/null
+++ b/packages/ai-harness/tests/view-media.test.ts
@@ -0,0 +1,401 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { HARNESS_EVENTS } from '../src'
+import { createSessionView, mediaPart } from '../src/view'
+import {
+  applyEvent,
+  emptyState,
+  messagesFromTranscript,
+} from '../src/view/reduce'
+import { at, sessionSnapshot } from './view-fixtures'
+import type { ModelMessage } from '@tanstack/ai'
+import type { MediaRecord, Receipt, SessionEvent, UserInput } from '../src'
+import type {
+  MediaPart,
+  SessionView,
+  SessionViewSource,
+  SessionViewState,
+  ViewPart,
+} from '../src/view'
+
+const MINUTE = 60_000
+const HOUR = 60 * MINUTE
+const receipt: Receipt = { inputId: 'i', status: 'accepted' }
+
+function record(over: Partial<MediaRecord> = {}): MediaRecord {
+  return {
+    id: 'm1',
+    threadId: 't',
+    kind: 'image',
+    mimeType: 'image/png',
+    name: 'cat.png',
+    size: 3,
+    source: 'generated',
+    createdAt: 0,
+    ...over,
+  }
+}
+
+/** The media part the view shows for `record()`, with `over` on top. */
+function shown(over: Partial<MediaPart> = {}) {
+  return {
+    type: 'media',
+    id: 'm1',
+    kind: 'image',
+    mimeType: 'image/png',
+    name: 'cat.png',
+    size: 3,
+    load: expect.any(Function),
+    ...over,
+  }
+}
+
+/** The `harness.media` event of a turn. */
+function mediaEvent(media: MediaRecord) {
+  return at({
+    type: EventType.CUSTOM,
+    name: HARNESS_EVENTS.media,
+    value: media,
+  })
+}
+
+function savedAnswer(media: Array<MediaRecord>): ModelMessage {
+  return {
+    role: 'assistant',
+    content: 'Here it is.',
+    metadata: { harness: { media } },
+  }
+}
+
+const fold = (events: Array<SessionEvent>) =>
+  events.reduce(applyEvent, emptyState())
+
+function assistantParts(state: SessionViewState) {
+  const message = state.messages.find((item) => item.role === 'assistant')
+  return message?.role === 'assistant' ? message.parts : []
+}
+
+function mediaOfParts(parts: ReadonlyArray<ViewPart>): Array<MediaPart> {
+  return parts.flatMap((part) => {
+    if (part.type === 'media') return [part]
+    return part.type === 'agent' ? mediaOfParts(part.parts) : []
+  })
+}
+
+/** Every media part in the view, in message order. */
+function mediaIn(view: SessionView) {
+  return view.store
+    .get()
+    .messages.flatMap((message) =>
+      message.role === 'assistant'
+        ? mediaOfParts(message.parts)
+        : message.role === 'user'
+          ? (message.media ?? [])
+          : [],
+    )
+}
+
+/** `entries`, then nothing until the view stops reading. */
+async function* replay(
+  entries: Array<SessionEvent>,
+  signal: AbortSignal | undefined,
+) {
+  yield* entries
+  await new Promise((resolve) => signal?.addEventListener('abort', resolve))
+}
+
+/** A view on a source that records what the view sends. */
+async function openView(over: Partial<SessionViewSource> = {}) {
+  const sent: Array<UserInput> = []
+  const commands: Array<{ name: string; input: unknown }> = []
+  const source: SessionViewSource = {
+    prompt: (message) => {
+      sent.push(message)
+    },
+    steer: async (message) => {
+      sent.push(message)
+      return receipt
+    },
+    resolve: async () => receipt,
+    cancel: async () => receipt,
+    answer: async () => receipt,
+    command: (name, input) => {
+      commands.push({ name, input })
+    },
+    setConfig: async () => receipt,
+    events: ({ signal }) => replay([], signal),
+    snapshot: () => sessionSnapshot(),
+    transcript: async () => [],
+    describe: () => ({ commands: [], config: [], tools: [] }),
+    ...over,
+  }
+  const view = createSessionView(source)
+  await view.ready
+  return { view, sent, commands }
+}
+
+/** A source whose URLs expire an hour after each call, and the ids it was asked for. */
+function expiringUrls() {
+  const asked: Array<string> = []
+  const mediaUrl = async (id: string) => {
+    asked.push(id)
+    return {
+      url: `https://media.test/${id}?v=${asked.length}`,
+      expiresAt: Date.now() + HOUR,
+    }
+  }
+  return { asked, mediaUrl }
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('media in the view reducer', () => {
+  it('puts generated media inside the child agent part that made it', () => {
+    const state = fold([
+      at({
+        subagentRunId: 'child-1',
+        type: EventType.SUBAGENT_STARTED,
+        name: 'painter',
+      }),
+      mediaEvent(record({ subagentRunId: 'child-1' })),
+    ])
+    expect(assistantParts(state)).toEqual([
+      {
+        type: 'agent',
+        id: 'child-1',
+        name: 'painter',
+        status: 'running',
+        parts: [shown()],
+      },
+    ])
+  })
+
+  it('puts media with no known child in the lead parts of its turn, once per id', () => {
+    const state = fold([
+      at({ type: EventType.TEXT_MESSAGE_CONTENT, messageId: 'm', delta: 'Hi' }),
+      mediaEvent(record()),
+      mediaEvent(record({ id: 'm2', name: 'dog.png', subagentRunId: 'gone' })),
+      mediaEvent(record()),
+    ])
+    expect(assistantParts(state)).toEqual([
+      { type: 'text', text: 'Hi' },
+      shown(),
+      shown({ id: 'm2', name: 'dog.png' }),
+    ])
+  })
+
+  it('reads user media parts and the media saved on an assistant message', () => {
+    const messages = messagesFromTranscript([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', content: 'What is this?' },
+          mediaPart(record({ id: 'u1', source: 'user' })),
+        ],
+      },
+      savedAnswer([record({ id: 'm2', name: 'dog.png' })]),
+    ])
+    expect(messages).toEqual([
+      {
+        id: 'history-0',
+        role: 'user',
+        text: 'What is this?',
+        // A saved part keeps only its id and MIME type.
+        media: [shown({ id: 'u1', name: 'u1', size: 0 })],
+      },
+      {
+        id: 'history-1',
+        role: 'assistant',
+        parts: [
+          { type: 'text', text: 'Here it is.' },
+          shown({ id: 'm2', name: 'dog.png' }),
+        ],
+      },
+    ])
+  })
+})
+
+describe('media in createSessionView', () => {
+  it('sends attachments as media parts and shows them on the user message', async () => {
+    const { view, sent } = await openView()
+
+    await view.send('What is this?', [record({ id: 'u1', source: 'user' })])
+    await view.send('', [record({ id: 'u2', source: 'user' })])
+
+    expect(sent).toEqual([
+      [
+        { type: 'text', content: 'What is this?' },
+        {
+          type: 'image',
+          source: {
+            type: 'url',
+            value: 'harness-media:u1',
+            mimeType: 'image/png',
+          },
+        },
+      ],
+      [
+        {
+          type: 'image',
+          source: {
+            type: 'url',
+            value: 'harness-media:u2',
+            mimeType: 'image/png',
+          },
+        },
+      ],
+    ])
+    expect(view.store.get().messages).toEqual([
+      {
+        id: 'user-0',
+        role: 'user',
+        text: 'What is this?',
+        media: [shown({ id: 'u1' })],
+      },
+      { id: 'user-1', role: 'user', text: '', media: [shown({ id: 'u2' })] },
+    ])
+    view.dispose()
+  })
+
+  it('runs a /command and drops its attachments', async () => {
+    const { view, sent, commands } = await openView()
+
+    await view.send('/ping now', [record()])
+
+    expect(commands).toEqual([{ name: 'ping', input: 'now' }])
+    expect(sent).toEqual([])
+    expect(view.store.get().messages).toEqual([])
+    view.dispose()
+  })
+
+  it('fills in each url once, then gets a new one a minute before it expires', async () => {
+    vi.useFakeTimers({ now: 0 })
+    const { asked, mediaUrl } = expiringUrls()
+    const { view } = await openView({
+      transcript: async () => [
+        savedAnswer([record()]),
+        savedAnswer([record()]),
+      ],
+      mediaUrl,
+    })
+    const urls = () => mediaIn(view).map((part) => part.url)
+
+    await vi.waitFor(() =>
+      expect(urls()).toEqual([
+        'https://media.test/m1?v=1',
+        'https://media.test/m1?v=1',
+      ]),
+    )
+    expect(asked).toEqual(['m1'])
+
+    await vi.advanceTimersByTimeAsync(HOUR - MINUTE - 1 - Date.now())
+    expect(asked).toEqual(['m1'])
+    await vi.advanceTimersByTimeAsync(1)
+
+    await vi.waitFor(() =>
+      expect(urls()).toEqual([
+        'https://media.test/m1?v=2',
+        'https://media.test/m1?v=2',
+      ]),
+    )
+    expect(asked).toEqual(['m1', 'm1'])
+    view.dispose()
+  })
+
+  it('stops getting new urls for media that no message shows after a revert', async () => {
+    vi.useFakeTimers({ now: 0 })
+    const { asked, mediaUrl } = expiringUrls()
+    // The first read has the image. The read after the revert has none.
+    const transcript = vi
+      .fn<() => Promise<Array<ModelMessage>>>()
+      .mockResolvedValueOnce([savedAnswer([record()])])
+      .mockResolvedValue([])
+    const reverted = at({
+      type: EventType.CUSTOM,
+      name: HARNESS_EVENTS.revert,
+      value: { messageId: 'u1' },
+    })
+    const { view } = await openView({
+      transcript,
+      mediaUrl,
+      events: ({ signal }) => replay([reverted], signal),
+    })
+
+    await vi.waitFor(() => expect(mediaIn(view)).toEqual([]))
+    await vi.advanceTimersByTimeAsync(2 * HOUR)
+
+    expect(asked).toEqual(['m1'])
+    view.dispose()
+  })
+
+  it('shows an error when the source cannot give a url', async () => {
+    const { view } = await openView({
+      transcript: async () => [savedAnswer([record()])],
+      mediaUrl: async () => {
+        throw new Error('Media not found.')
+      },
+    })
+
+    await vi.waitFor(() =>
+      expect(view.store.get().messages.at(-1)).toMatchObject({
+        role: 'notice',
+        kind: 'error',
+        text: 'Media not found.',
+      }),
+    )
+    expect(mediaIn(view)).toEqual([shown()])
+    view.dispose()
+  })
+
+  it('loads the bytes of media inside a child agent part', async () => {
+    const { view } = await openView({
+      events: ({ signal }) =>
+        replay(
+          [
+            at({
+              subagentRunId: 'child-1',
+              type: EventType.SUBAGENT_STARTED,
+              name: 'painter',
+            }),
+            mediaEvent(record({ subagentRunId: 'child-1' })),
+          ],
+          signal,
+        ),
+      loadMedia: async (id) => new TextEncoder().encode(`bytes of ${id}`),
+    })
+
+    await vi.waitFor(() => expect(mediaIn(view)).toHaveLength(1))
+    const [part] = mediaIn(view)
+
+    expect(new TextDecoder().decode(await part?.load())).toBe('bytes of m1')
+    view.dispose()
+  })
+
+  it('rejects load() when the source cannot load media', async () => {
+    const { view } = await openView({
+      transcript: async () => [savedAnswer([record()])],
+    })
+    const [part] = mediaIn(view)
+
+    await expect(part?.load()).rejects.toThrow('cannot load media')
+    view.dispose()
+  })
+
+  it('clears the url refresh timers on dispose', async () => {
+    vi.useFakeTimers({ now: 0 })
+    const { asked, mediaUrl } = expiringUrls()
+    const { view } = await openView({
+      transcript: async () => [savedAnswer([record()])],
+      mediaUrl,
+    })
+    await vi.waitFor(() => expect(vi.getTimerCount()).toBe(1))
+
+    view.dispose()
+    await vi.advanceTimersByTimeAsync(HOUR)
+
+    expect(vi.getTimerCount()).toBe(0)
+    expect(asked).toEqual(['m1'])
+  })
+})
diff --git a/packages/ai-harness/tests/view-paths.test.ts b/packages/ai-harness/tests/view-paths.test.ts
new file mode 100644
index 0000000000..c60ec02cad
--- /dev/null
+++ b/packages/ai-harness/tests/view-paths.test.ts
@@ -0,0 +1,1433 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { HARNESS_EVENTS, createPluginEvent } from '../src'
+import { createSessionView } from '../src/view'
+import { gate } from './helpers'
+import { at, childRun, custom, sessionSnapshot } from './view-fixtures'
+import { emptyUsage } from '../src/usage'
+import type { Interrupt, StreamChunk } from '@tanstack/ai'
+import type {
+  Cursor,
+  HarnessInput,
+  MediaRecord,
+  Receipt,
+  SessionDescription,
+  SessionEvent,
+} from '../src'
+import type { SessionView, SessionViewSource } from '../src/view'
+
+type StreamOptions = Parameters<SessionViewSource['events']>[0]
+
+const accepted: Receipt = { inputId: 'i', status: 'accepted' }
+
+/** An event stream the test writes to. It ends when the view aborts it. */
+function createStream() {
+  const queue: Array<SessionEvent> = []
+  const opened: Array<StreamOptions> = []
+  let wake = () => {}
+  let ended = false
+  let closed = false
+  let failure: { error: unknown } | null = null
+  const end = () => {
+    ended = true
+    wake()
+  }
+  async function* iterate() {
+    try {
+      while (true) {
+        const entry = queue.shift()
+        if (entry) {
+          yield entry
+          continue
+        }
+        if (failure) throw failure.error
+        if (ended) return
+        await new Promise<void>((resolve) => {
+          wake = resolve
+        })
+      }
+    } finally {
+      closed = true
+    }
+  }
+  return {
+    /** The options of each `events()` call. */
+    opened,
+    /** True once the view stopped reading. */
+    closed: () => closed,
+    open: (options: StreamOptions) => {
+      opened.push(options)
+      options.signal?.addEventListener('abort', end, { once: true })
+      return iterate()
+    },
+    push: (...entries: Array<SessionEvent>) => {
+      queue.push(...entries)
+      wake()
+    },
+    end,
+    fail: (error: unknown) => {
+      failure = { error }
+      wake()
+    },
+    connect: (connection: 'open' | 'reconnecting') =>
+      opened.at(-1)?.onConnection?.(connection),
+  }
+}
+
+function emptyDescription(): SessionDescription {
+  return { commands: [], config: [], tools: [] }
+}
+
+/** A session source whose reads and events the test controls. */
+function createFake(overrides: Partial<SessionViewSource>) {
+  const stream = createStream()
+  /** What reached the session. */
+  const inputs: Array<HarnessInput> = []
+  const accept = async (input: HarnessInput) => {
+    inputs.push(input)
+    return accepted
+  }
+  const source: SessionViewSource = {
+    prompt: (message) => accept({ op: 'prompt', message }),
+    steer: (message) => accept({ op: 'steer', message }),
+    resolve: (resume) => accept({ op: 'resolve', resume }),
+    cancel: () => accept({ op: 'cancel' }),
+    answer: ({ questionId, value }) =>
+      accept({ op: 'answer', questionId, value }),
+    command: (name, input) => accept({ op: 'command', name, input }),
+    setConfig: ({ key, value }) => accept({ op: 'config', key, value }),
+    events: (options) => stream.open(options),
+    snapshot: () => sessionSnapshot(),
+    transcript: async () => [],
+    describe: () => emptyDescription(),
+    ...overrides,
+  }
+  return { stream, inputs, source }
+}
+
+const views: Array<SessionView> = []
+afterEach(() => {
+  for (const view of views.splice(0)) view.dispose()
+})
+
+/** A view on a fake source, with the errors it reports. */
+function startView(overrides: Partial<SessionViewSource> = {}) {
+  const fake = createFake(overrides)
+  const view = createSessionView(fake.source)
+  views.push(view)
+  const errors: Array<string> = []
+  view.on('error', (message) => errors.push(message))
+  return { ...fake, view, errors }
+}
+
+/** `startView`, after the view read the session once. */
+async function openView(overrides: Partial<SessionViewSource> = {}) {
+  const started = startView(overrides)
+  await started.view.ready
+  return started
+}
+
+/** Let every pending promise callback run. No timer picks a branch. */
+const drain = () => new Promise<void>((resolve) => setImmediate(resolve))
+
+const says = (delta: string) =>
+  at({ type: EventType.TEXT_MESSAGE_CONTENT, messageId: 'm', delta })
+const runStarted = () =>
+  at({ type: EventType.RUN_STARTED, threadId: 't', runId: 'r' })
+const runFinished = () =>
+  at({ type: EventType.RUN_FINISHED, threadId: 't', runId: 'r' })
+
+function notices(view: SessionView) {
+  return view.store
+    .get()
+    .messages.flatMap((message) =>
+      message.role === 'notice'
+        ? [{ kind: message.kind, text: message.text }]
+        : [],
+    )
+}
+
+function assistantText(view: SessionView) {
+  return view.store
+    .get()
+    .messages.flatMap((message) =>
+      message.role === 'assistant' ? message.parts : [],
+    )
+    .flatMap((part) => (part.type === 'text' ? [part.text] : []))
+    .join('')
+}
+
+const deleteFile: Interrupt = {
+  id: 'a',
+  reason: 'confirm',
+  message: 'Delete the file?',
+}
+const plain: Interrupt = { id: 'b', reason: 'confirm' }
+const waiting = sessionSnapshot({
+  status: 'requires_action',
+  pendingInterrupts: [deleteFile, plain],
+})
+const confirm = {
+  questionId: 'q1',
+  message: 'Sure?',
+  schema: { type: 'boolean' },
+}
+const planCommand = {
+  name: 'plan',
+  description: 'Plan first',
+  owner: 'test/planner',
+}
+
+describe('session view start', () => {
+  const failedReads: Array<{
+    read: string
+    overrides: Partial<SessionViewSource>
+    from: Cursor | undefined
+  }> = [
+    {
+      read: 'transcript',
+      overrides: {
+        transcript: () => Promise.reject(new Error('transcript down')),
+      },
+      from: '0',
+    },
+    {
+      // With no snapshot there is no cursor, so events come from the start.
+      read: 'snapshot',
+      overrides: { snapshot: () => Promise.reject(new Error('snapshot down')) },
+      from: undefined,
+    },
+    {
+      read: 'describe',
+      overrides: { describe: () => Promise.reject(new Error('describe down')) },
+      from: '0',
+    },
+  ]
+
+  it.each(failedReads)(
+    'shows a failed $read read and still reads events',
+    async ({ read, overrides, from }) => {
+      const { view, stream, errors } = await openView(overrides)
+
+      stream.push(says('Still here.'))
+
+      await vi.waitFor(() => expect(assistantText(view)).toBe('Still here.'))
+      expect(errors).toEqual([`${read} down`])
+      expect(notices(view)).toEqual([{ kind: 'error', text: `${read} down` }])
+      expect(stream.opened[0]?.from).toBe(from)
+    },
+  )
+
+  it('does not read events when disposed before start ends', async () => {
+    const hold = gate()
+    const { view, stream } = startView({
+      transcript: async () => {
+        await hold.opened
+        return [{ role: 'user', content: 'old question' }]
+      },
+    })
+
+    view.dispose()
+    hold.open()
+    await view.ready
+
+    expect(stream.opened).toEqual([])
+    expect(view.store.get().messages).toEqual([])
+    expect(view.store.get().connection).toBe('closed')
+  })
+})
+
+describe('session view events', () => {
+  it('shows a failed event stream as an error, then closes', async () => {
+    const { view, stream, errors } = await openView()
+
+    // A source can throw a value that is not an Error.
+    stream.fail('socket closed')
+
+    await vi.waitFor(() => expect(view.store.get().connection).toBe('closed'))
+    expect(errors).toEqual(['socket closed'])
+    expect(notices(view)).toEqual([{ kind: 'error', text: 'socket closed' }])
+  })
+
+  it('closes when the event stream ends', async () => {
+    const { view, stream, errors } = await openView()
+
+    stream.end()
+
+    await vi.waitFor(() => expect(view.store.get().connection).toBe('closed'))
+    expect(errors).toEqual([])
+  })
+
+  it('follows the connection state that the source reports', async () => {
+    const { view, stream } = await openView()
+
+    stream.connect('reconnecting')
+    expect(view.store.get().connection).toBe('reconnecting')
+
+    stream.connect('open')
+    expect(view.store.get().connection).toBe('open')
+  })
+
+  it('ignores an event that comes after dispose', async () => {
+    const { view, stream } = await openView()
+    const calls: Array<string> = []
+    view.on('toolCall', (call) => calls.push(call.id))
+
+    view.dispose()
+    stream.push(
+      at({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c1',
+        toolCallName: 'read',
+      }),
+    )
+
+    await vi.waitFor(() => expect(stream.closed()).toBe(true))
+    expect(calls).toEqual([])
+    expect(view.store.get().messages).toEqual([])
+  })
+
+  it('reads the snapshot again after a lead run event, not after a child run event', async () => {
+    const snapshot = vi.fn(() => sessionSnapshot({ queuedTurns: 1 }))
+    snapshot.mockReturnValueOnce(sessionSnapshot())
+    const { view, stream } = await openView({ snapshot })
+
+    stream.push(at(childRun.started), at(childRun.finished), runFinished())
+
+    await vi.waitFor(() => expect(view.store.get().queuedTurns).toBe(1))
+    await drain()
+    expect(snapshot).toHaveBeenCalledTimes(2)
+  })
+
+  it('reads the snapshot once more for events that come during a read', async () => {
+    const hold = gate()
+    const snapshot = vi.fn(async () => sessionSnapshot({ queuedTurns: 2 }))
+    snapshot
+      .mockResolvedValueOnce(sessionSnapshot())
+      .mockReturnValueOnce(
+        hold.opened.then(() => sessionSnapshot({ queuedTurns: 1 })),
+      )
+    const { view, stream } = await openView({ snapshot })
+
+    stream.push(
+      runStarted(),
+      runFinished(),
+      custom(HARNESS_EVENTS.operationFinished, { operationId: 'op-1' }),
+      says('Done.'),
+    )
+    await vi.waitFor(() => expect(assistantText(view)).toBe('Done.'))
+    hold.open()
+
+    await vi.waitFor(() => expect(view.store.get().queuedTurns).toBe(2))
+    await drain()
+    expect(snapshot).toHaveBeenCalledTimes(3)
+  })
+
+  it('shows a failed snapshot read after an event', async () => {
+    const snapshot = vi.fn(async () => sessionSnapshot())
+    snapshot
+      .mockResolvedValueOnce(sessionSnapshot())
+      .mockRejectedValueOnce(new Error('snapshot down'))
+    const { view, stream, errors } = await openView({ snapshot })
+
+    stream.push(runFinished())
+
+    await vi.waitFor(() => expect(errors).toEqual(['snapshot down']))
+    expect(notices(view)).toEqual([{ kind: 'error', text: 'snapshot down' }])
+  })
+
+  it('reads the description again after a setting changes', async () => {
+    const describeSession = vi.fn(() => ({
+      ...emptyDescription(),
+      commands: [planCommand],
+    }))
+    describeSession.mockReturnValueOnce(emptyDescription())
+    const { view, stream } = await openView({ describe: describeSession })
+    expect(view.store.get().commands).toEqual([])
+
+    stream.push(
+      custom(HARNESS_EVENTS.configChanged, { key: 'mode', value: 'plan' }),
+    )
+
+    await vi.waitFor(() =>
+      expect(view.store.get().commands).toEqual([planCommand]),
+    )
+  })
+
+  it('shows a failed description read after a setting changes', async () => {
+    const describeSession = vi.fn(async () => emptyDescription())
+    describeSession
+      .mockResolvedValueOnce(emptyDescription())
+      .mockRejectedValueOnce(new Error('describe down'))
+    const { stream, errors } = await openView({ describe: describeSession })
+
+    stream.push(
+      custom(HARNESS_EVENTS.configChanged, { key: 'mode', value: 'plan' }),
+    )
+
+    await vi.waitFor(() => expect(errors).toEqual(['describe down']))
+  })
+
+  it('ignores reads that end after dispose', async () => {
+    const hold = gate()
+    const snapshot = vi.fn(async () => {
+      await hold.opened
+      return waiting
+    })
+    snapshot.mockResolvedValueOnce(sessionSnapshot())
+    const describeSession = vi.fn(async () => {
+      await hold.opened
+      return { ...emptyDescription(), commands: [planCommand] }
+    })
+    describeSession.mockResolvedValueOnce(emptyDescription())
+    const { view, stream } = await openView({
+      snapshot,
+      describe: describeSession,
+    })
+    const asked: Array<string> = []
+    view.on('approval', (approval) => asked.push(approval.id))
+
+    stream.push(
+      runFinished(),
+      custom(HARNESS_EVENTS.configChanged, { key: 'mode', value: 'plan' }),
+    )
+    await vi.waitFor(() => {
+      expect(snapshot).toHaveBeenCalledTimes(2)
+      expect(describeSession).toHaveBeenCalledTimes(2)
+    })
+    view.dispose()
+    hold.open()
+    await drain()
+
+    expect(asked).toEqual([])
+    expect(view.store.get().approvals).toEqual([])
+    expect(view.store.get().commands).toEqual([])
+  })
+
+  it('ignores a failure that comes after dispose', async () => {
+    const hold = gate()
+    const { view, errors } = await openView({
+      cancel: async () => {
+        await hold.opened
+        throw new Error('late failure')
+      },
+    })
+
+    const cancelling = view.cancel()
+    view.dispose()
+    hold.open()
+    await cancelling
+
+    expect(errors).toEqual([])
+  })
+})
+
+describe('session view actions', () => {
+  it('sends settings, cancels, and slash commands with input to the source', async () => {
+    const { view, inputs } = await openView()
+
+    await view.setConfig({ key: 'mode', value: 'plan' })
+    await view.cancel()
+    await view.send('/goal ship it')
+
+    expect(inputs).toEqual([
+      { op: 'config', key: 'mode', value: 'plan' },
+      { op: 'cancel' },
+      { op: 'command', name: 'goal', input: 'ship it' },
+    ])
+  })
+
+  const down = () =>
+    Promise.reject(new Error('Harness request failed (500): down'))
+  const failingActions: Array<{
+    action: string
+    overrides: Partial<SessionViewSource>
+    act: (view: SessionView) => Promise<void>
+  }> = [
+    {
+      action: 'setConfig',
+      overrides: { setConfig: down },
+      act: (view) => view.setConfig({ key: 'mode', value: 'plan' }),
+    },
+    {
+      action: 'cancel',
+      overrides: { cancel: down },
+      act: (view) => view.cancel(),
+    },
+    {
+      action: 'a steer',
+      overrides: {
+        steer: down,
+        snapshot: () => sessionSnapshot({ status: 'running' }),
+      },
+      act: (view) => view.send('faster'),
+    },
+    {
+      action: 'a remote prompt',
+      overrides: { prompt: down },
+      act: (view) => view.send('hi'),
+    },
+    {
+      action: 'a remote command',
+      overrides: { command: down },
+      act: (view) => view.send('/ping'),
+    },
+  ]
+
+  it.each(failingActions)(
+    'shows an error notice when $action fails',
+    async ({ overrides, act }) => {
+      const { view, errors } = await openView(overrides)
+
+      await act(view)
+
+      await vi.waitFor(() =>
+        expect(errors).toEqual(['Harness request failed (500): down']),
+      )
+      expect(notices(view)).toEqual([
+        { kind: 'error', text: 'Harness request failed (500): down' },
+      ])
+    },
+  )
+
+  it('adds nothing when a local operation fails', async () => {
+    const { view, errors } = await openView({
+      // A local session returns an Operation. It reports failures as events.
+      prompt: () =>
+        Object.assign(Promise.reject(new Error('turn failed')), {
+          status: () => 'failed',
+        }),
+    })
+
+    await view.send('hi')
+    await drain()
+
+    expect(errors).toEqual([])
+    expect(view.store.get().messages).toEqual([
+      { id: 'user-0', role: 'user', text: 'hi' },
+    ])
+  })
+})
+
+describe('session view approvals', () => {
+  it('makes approvals from interrupts that have no tool call', async () => {
+    const { view } = await openView({ snapshot: () => waiting })
+
+    // Strict: no `toolCallId` key, and no `message` key when there is none.
+    expect(view.store.get().approvals).toStrictEqual([
+      {
+        id: 'a',
+        tool: 'Delete the file?',
+        args: undefined,
+        message: 'Delete the file?',
+        approve: expect.any(Function),
+        reject: expect.any(Function),
+      },
+      {
+        id: 'b',
+        tool: 'tool',
+        args: undefined,
+        approve: expect.any(Function),
+        reject: expect.any(Function),
+      },
+    ])
+  })
+
+  it('rejects every approval with one resolve', async () => {
+    const snapshot = vi.fn(() => sessionSnapshot())
+    snapshot.mockReturnValueOnce(waiting)
+    const { view, inputs } = await openView({ snapshot })
+
+    view.rejectAll()
+
+    expect(inputs).toEqual([
+      {
+        op: 'resolve',
+        resume: [
+          { interruptId: 'a', status: 'resolved', payload: false },
+          { interruptId: 'b', status: 'resolved', payload: false },
+        ],
+      },
+    ])
+    expect(view.store.get().approvals).toEqual([])
+  })
+
+  it('ignores a decision for an approval that is not open, also when it opens later', async () => {
+    const late: Interrupt = { id: 'late', reason: 'confirm' }
+    const snapshot = vi.fn(() =>
+      sessionSnapshot({ pendingInterrupts: [deleteFile, late] }),
+    )
+    snapshot.mockReturnValueOnce(
+      sessionSnapshot({ pendingInterrupts: [deleteFile] }),
+    )
+    const { view, stream, inputs } = await openView({ snapshot })
+
+    view.approve('late')
+    stream.push(runFinished())
+    await vi.waitFor(() => expect(view.store.get().approvals).toHaveLength(2))
+    view.approve('a')
+
+    // `late` still waits for its own answer.
+    expect(inputs).toEqual([])
+  })
+
+  it('shows a failed resolve, then reads the snapshot again', async () => {
+    const snapshot = vi.fn(() => waiting)
+    const { view, errors } = await openView({
+      snapshot,
+      resolve: () => Promise.reject(new Error('resolve down')),
+    })
+
+    view.approveAll()
+    expect(view.store.get().approvals).toEqual([])
+
+    await vi.waitFor(() => expect(view.store.get().approvals).toHaveLength(2))
+    expect(errors).toEqual(['resolve down'])
+    expect(snapshot).toHaveBeenCalledTimes(2)
+  })
+})
+
+describe('session view on()', () => {
+  const configDown = () => Promise.reject(new Error('config down'))
+
+  it('stops calling a handler after it unsubscribes', async () => {
+    const { view, errors } = await openView({ setConfig: configDown })
+    const heard: Array<string> = []
+    const stop = view.on('error', (message) => heard.push(message))
+
+    stop()
+    await view.setConfig({ key: 'mode', value: 'plan' })
+
+    expect(errors).toEqual(['config down'])
+    expect(heard).toEqual([])
+  })
+
+  it('calls the next handler when one throws', async () => {
+    const { view } = await openView({ setConfig: configDown })
+    const heard: Array<string> = []
+    view.on('error', () => {
+      throw new Error('broken handler')
+    })
+    view.on('error', (message) => heard.push(message))
+
+    await view.setConfig({ key: 'mode', value: 'plan' })
+
+    expect(heard).toEqual(['config down'])
+  })
+
+  it('sends plugin events to their handlers', async () => {
+    const Pinged = createPluginEvent<{ count: number }>('test/pinged')
+    const Numbered = createPluginEvent<{ count: number }>('7')
+    const { view, stream } = await openView()
+    const pings: Array<{ count: number }> = []
+    const numbered: Array<{ count: number }> = []
+    view.on(Pinged, (value) => pings.push(value))
+    view.on(Numbered, (value) => numbered.push(value))
+
+    stream.push(
+      // A plugin event needs a string name.
+      custom(HARNESS_EVENTS.pluginEvent, { name: 7, value: { count: 1 } }),
+      custom('test.note', null),
+      custom(HARNESS_EVENTS.pluginEvent, {
+        plugin: 'test/p',
+        name: 'test/pinged',
+        value: { count: 3 },
+      }),
+    )
+
+    await vi.waitFor(() => expect(pings).toEqual([{ count: 3 }]))
+    expect(numbered).toEqual([])
+  })
+
+  it('fires toolCall and agent events', async () => {
+    const { view, stream } = await openView()
+    const calls: Array<{ id: string; name: string }> = []
+    const agents: Array<{ id: string; name: string; status: string }> = []
+    view.on('toolCall', (call) => calls.push(call))
+    view.on('agent', (agent) => agents.push(agent))
+
+    stream.push(
+      at({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c1',
+        toolCallName: 'read',
+      }),
+      at({
+        type: EventType.SUBAGENT_STARTED,
+        subagentRunId: 's1',
+        name: 'helper',
+      }),
+      at({ type: EventType.SUBAGENT_FINISHED, subagentRunId: 's1' }),
+      at({
+        type: EventType.SUBAGENT_STARTED,
+        subagentRunId: 's2',
+        name: 'fixer',
+      }),
+      at({
+        type: EventType.SUBAGENT_ERROR,
+        subagentRunId: 's2',
+        message: 'no key',
+      }),
+      // An error for a child whose start the view never saw.
+      at({
+        type: EventType.SUBAGENT_ERROR,
+        subagentRunId: 'ghost',
+        message: 'lost',
+      }),
+    )
+
+    await vi.waitFor(() => expect(agents).toHaveLength(5))
+    expect(calls).toEqual([{ id: 'c1', name: 'read' }])
+    expect(agents).toEqual([
+      { id: 's1', name: 'helper', status: 'running' },
+      { id: 's1', name: 'helper', status: 'done' },
+      { id: 's2', name: 'fixer', status: 'running' },
+      { id: 's2', name: 'fixer', status: 'failed' },
+      { id: 'ghost', name: 'agent', status: 'failed' },
+    ])
+  })
+
+  it('fires each question once, and answers it through the source', async () => {
+    const named = { questionId: 'q2', message: 'Name?' }
+    const snapshot = vi.fn(() =>
+      sessionSnapshot({ pendingQuestions: [confirm, named], queuedTurns: 1 }),
+    )
+    snapshot.mockReturnValueOnce(
+      sessionSnapshot({ pendingQuestions: [confirm, named] }),
+    )
+    const { view, stream, inputs } = startView({ snapshot })
+    const asked: Array<string> = []
+    view.on('question', (question) => asked.push(question.id))
+    await view.ready
+
+    stream.push(runFinished())
+    await vi.waitFor(() => expect(view.store.get().queuedTurns).toBe(1))
+
+    expect(asked).toEqual(['q1', 'q2'])
+    // Strict: a question without a schema has no `schema` key.
+    expect(view.store.get().questions).toStrictEqual([
+      {
+        id: 'q1',
+        message: 'Sure?',
+        schema: { type: 'boolean' },
+        answer: expect.any(Function),
+      },
+      { id: 'q2', message: 'Name?', answer: expect.any(Function) },
+    ])
+    await view.store.get().questions[0]?.answer(true)
+    expect(inputs).toEqual([{ op: 'answer', questionId: 'q1', value: true }])
+  })
+
+  it('fires a sign-in event once for a connector that needs one', async () => {
+    const { view, stream } = await openView()
+    const signIns: Array<{ connector: string }> = []
+    view.on('signIn', (signIn) => signIns.push(signIn))
+
+    stream.push(
+      custom(HARNESS_EVENTS.authRequired, {
+        connector: 'notion',
+        url: 'https://notion.example/auth',
+        userCode: 'AB-12',
+      }),
+      says('Waiting.'),
+    )
+
+    await vi.waitFor(() => expect(assistantText(view)).toBe('Waiting.'))
+    expect(signIns).toEqual([
+      {
+        connector: 'notion',
+        url: 'https://notion.example/auth',
+        userCode: 'AB-12',
+      },
+    ])
+  })
+
+  it('fires turnEnd only for chat operations', async () => {
+    const { view, stream } = await openView()
+    const ended: Array<string> = []
+    view.on('turnEnd', ({ operationId }) => ended.push(operationId))
+
+    stream.push(
+      custom(HARNESS_EVENTS.operationStarted, {
+        operationId: 'op-c',
+        kind: 'command',
+      }),
+      custom(HARNESS_EVENTS.operationFinished, { operationId: 'op-c' }),
+      custom(HARNESS_EVENTS.operationStarted, {
+        operationId: 'op-t',
+        kind: 'chat',
+      }),
+      custom(HARNESS_EVENTS.operationFinished, { operationId: 'op-t' }),
+    )
+
+    await vi.waitFor(() => expect(ended).toEqual(['op-t']))
+  })
+
+  it('reports a lead run error and a rejected input, not a child run error', async () => {
+    const { stream, errors } = await openView()
+
+    stream.push(
+      at(childRun.error),
+      custom(HARNESS_EVENTS.inputRejected, { inputId: 'i' }),
+      at({ type: EventType.RUN_ERROR, message: 'boom' }),
+    )
+
+    await vi.waitFor(() => expect(errors).toHaveLength(2))
+    expect(errors).toEqual(['Not accepted: unknown reason', 'Error: boom'])
+  })
+})
+
+const removeApproval: Interrupt = {
+  id: 'ap-1',
+  reason: 'tool_call',
+  toolCallId: 'c7',
+  metadata: {
+    'tanstack:interruptBinding': {
+      v: 1,
+      kind: 'tool-approval',
+      interruptId: 'ap-1',
+      toolName: 'remove',
+      toolCallId: 'c7',
+      originalArgs: { path: 'a.txt' },
+      inputSchemaHash: 'in',
+      approvalSchemaHash: 'approval',
+      responseSchemaHash: 'response',
+    },
+  },
+}
+const regionInput: Interrupt = {
+  id: 'mcp_input_c9',
+  reason: 'mcp_input',
+  message: 'Input required to run deploy',
+  toolCallId: 'c9',
+  metadata: {
+    'tanstack:interruptBinding': {
+      v: 1,
+      kind: 'generic',
+      interruptId: 'mcp_input_c9',
+    },
+    'tanstack:interruptPayload': { kind: 'form', request: { field: 'region' } },
+  },
+}
+const stopped = sessionSnapshot({
+  status: 'requires_action',
+  pendingInterrupts: [removeApproval, regionInput],
+})
+
+/** A source call that records its name and arguments in `calls`. */
+function recorder(calls: Array<Array<unknown>>) {
+  return (name: string) =>
+    async (...args: Array<unknown>) => {
+      calls.push([name, ...args])
+      return accepted
+    }
+}
+
+describe('session view inputs', () => {
+  it('sends follow-ups, waiting inputs, settings, and context changes to the source', async () => {
+    const calls: Array<Array<unknown>> = []
+    const record = recorder(calls)
+    const { view, errors } = await openView({
+      followUp: record('followUp'),
+      continue: record('continue'),
+      cancel: record('cancel'),
+      cancelInput: record('cancelInput'),
+      setDelivery: record('setDelivery'),
+      configure: record('configure'),
+      reset: record('reset'),
+      revert: record('revert'),
+      unrevert: record('unrevert'),
+    })
+
+    await view.followUp('then the tests')
+    await view.continue()
+    await view.cancel('op-2')
+    await view.cancelInput('in-1')
+    await view.setDelivery({ inputId: 'in-2', delivery: 'steer' })
+    await view.configure({ model: 'strong' })
+    await view.reset('Start over.')
+    await view.revert('m1')
+    await view.unrevert()
+    await drain()
+
+    expect(calls).toEqual([
+      ['followUp', 'then the tests'],
+      ['continue'],
+      ['cancel', 'op-2'],
+      ['cancelInput', 'in-1'],
+      ['setDelivery', { inputId: 'in-2', delivery: 'steer' }],
+      ['configure', { model: 'strong' }],
+      ['reset', 'Start over.'],
+      ['revert', 'm1'],
+      ['unrevert'],
+    ])
+    expect(view.store.get().messages).toEqual([
+      { id: 'user-0', role: 'user', text: 'then the tests' },
+    ])
+    expect(errors).toEqual([])
+  })
+
+  it('shows an error for an action the source does not have', async () => {
+    const { view, errors } = await openView()
+
+    await view.followUp('later')
+    await view.reset()
+    await view.continue()
+    await drain()
+
+    expect(errors).toEqual([
+      'This view source cannot follow up.',
+      'This view source cannot reset.',
+      'This view source cannot continue.',
+    ])
+  })
+
+  it('stores a file through the source, and rejects when it cannot', async () => {
+    const file: MediaRecord = {
+      id: 'f1',
+      threadId: 't',
+      kind: 'image',
+      mimeType: 'image/png',
+      name: 'a.png',
+      size: 1,
+      source: 'user',
+      createdAt: 0,
+    }
+    const putMedia = vi.fn(async () => file)
+    const info = { name: 'a.png', mimeType: 'image/png' }
+    const { view } = await openView({ putMedia })
+    const bare = await openView()
+
+    expect(await view.upload(new Uint8Array([1]), info)).toBe(file)
+    expect(putMedia).toHaveBeenCalledWith(new Uint8Array([1]), info)
+    await expect(bare.view.upload(new Uint8Array([1]), info)).rejects.toThrow(
+      'This view source cannot store media.',
+    )
+  })
+})
+
+describe('session view interrupts', () => {
+  it('answers an approval with edited arguments and an input request in one resolve', async () => {
+    const snapshot = vi.fn(() => sessionSnapshot())
+    snapshot.mockReturnValueOnce(stopped)
+    const started = startView({ snapshot })
+    const fired: Array<string> = []
+    started.view.on('interrupt', (item) => fired.push(item.id))
+    await started.view.ready
+    const { view, inputs } = started
+    const [approval] = view.store.get().approvals
+    const [request] = view.store.get().interrupts
+
+    // The view never saw the call, so the binding names the tool.
+    expect(approval).toMatchObject({ tool: 'remove', args: { path: 'a.txt' } })
+    expect(request).toMatchObject({
+      id: 'mcp_input_c9',
+      reason: 'mcp_input',
+      message: 'Input required to run deploy',
+      toolCallId: 'c9',
+      payload: { kind: 'form', request: { field: 'region' } },
+    })
+    expect(fired).toEqual(['mcp_input_c9'])
+    approval?.approve({ editedArgs: { path: 'b.txt' } })
+    expect(inputs).toEqual([])
+    request?.resolve({ region: 'eu' })
+
+    expect(inputs).toEqual([
+      {
+        op: 'resolve',
+        resume: [
+          {
+            interruptId: 'ap-1',
+            status: 'resolved',
+            payload: { editedArgs: { path: 'b.txt' }, approved: true },
+          },
+          {
+            interruptId: 'mcp_input_c9',
+            status: 'resolved',
+            payload: { region: 'eu' },
+          },
+        ],
+      },
+    ])
+    expect(view.store.get().interrupts).toEqual([])
+  })
+
+  it('rejects an approval with a payload, and cancels an input request', async () => {
+    const snapshot = vi.fn(() => sessionSnapshot())
+    snapshot.mockReturnValueOnce(stopped)
+    const { view, inputs } = await openView({ snapshot })
+
+    view.reject('ap-1', { reason: 'wrong file' })
+    view.store.get().interrupts[0]?.cancel()
+
+    expect(inputs).toEqual([
+      {
+        op: 'resolve',
+        resume: [
+          {
+            interruptId: 'ap-1',
+            status: 'resolved',
+            payload: { approved: false, payload: { reason: 'wrong file' } },
+          },
+          { interruptId: 'mcp_input_c9', status: 'cancelled' },
+        ],
+      },
+    ])
+  })
+
+  it('does not end a turn that stops for an interrupt', async () => {
+    const { view, stream } = await openView()
+    const ended: Array<string> = []
+    view.on('turnEnd', ({ operationId }) => ended.push(operationId))
+    const turn = (operationId: string, status: string) => [
+      custom(HARNESS_EVENTS.operationStarted, { operationId, kind: 'chat' }),
+      custom(HARNESS_EVENTS.operationFinished, { operationId, status }),
+    ]
+
+    stream.push(...turn('op-a', 'interrupted'), ...turn('op-b', 'completed'))
+
+    await vi.waitFor(() => expect(ended).toEqual(['op-b']))
+  })
+})
+
+/** A session event of `operationId` at `cursor`. */
+const entry = (
+  cursor: number,
+  event: StreamChunk,
+  operationId = 'op-1',
+): SessionEvent => ({ cursor: String(cursor), operationId, event })
+
+describe('session view reload', () => {
+  it('shows a running turn from its start, without what the transcript has', async () => {
+    const { view, stream } = await openView({
+      snapshot: () =>
+        sessionSnapshot({
+          status: 'running',
+          activeOperations: [{ id: 'op-1', kind: 'chat', startedCursor: '0' }],
+          cursor: '4',
+        }),
+      // The turn saved its first model call when its tool started.
+      transcript: async () => [
+        { id: 'u1', role: 'user', content: 'Clean up' },
+        {
+          id: 'm1',
+          role: 'assistant',
+          content: 'Looking.',
+          toolCalls: [
+            {
+              id: 'c1',
+              type: 'function',
+              function: { name: 'list', arguments: '{}' },
+            },
+          ],
+        },
+      ],
+    })
+    const reasoning = (messageId: string, delta: string) =>
+      ({ type: EventType.REASONING_MESSAGE_CONTENT, messageId, delta }) as const
+
+    stream.push(
+      entry(1, reasoning('r1', 'Plan.')),
+      entry(2, {
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm1',
+        delta: 'Looking.',
+      }),
+      entry(3, {
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c1',
+        toolCallName: 'list',
+      }),
+      entry(4, { type: EventType.TOOL_CALL_END, toolCallId: 'c1' }),
+      entry(5, {
+        type: EventType.TOOL_CALL_RESULT,
+        toolCallId: 'c1',
+        messageId: 'x',
+        content: '["a.txt"]',
+      }),
+      entry(6, reasoning('r2', 'Next.')),
+      entry(7, {
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm2',
+        delta: 'Done.',
+      }),
+    )
+
+    await vi.waitFor(() => expect(assistantText(view)).toBe('Looking.Done.'))
+    expect(stream.opened[0]?.from).toBe('0')
+    expect(view.store.get().messages).toMatchObject([
+      { role: 'user', text: 'Clean up' },
+      {
+        role: 'assistant',
+        parts: [
+          { type: 'text', text: 'Looking.' },
+          { type: 'tool-call', id: 'c1', status: 'done', result: ['a.txt'] },
+        ],
+      },
+      {
+        id: 'turn-op-1',
+        role: 'assistant',
+        parts: [
+          { type: 'reasoning', text: 'Next.' },
+          { type: 'text', text: 'Done.' },
+        ],
+      },
+    ])
+  })
+
+  it('drops the reasoning of each saved model call, also when the replay comes in chunks', async () => {
+    const call = (id: string) => ({
+      id,
+      type: 'function' as const,
+      function: { name: 'list', arguments: '{}' },
+    })
+    const { view, stream } = await openView({
+      snapshot: () =>
+        sessionSnapshot({
+          status: 'running',
+          activeOperations: [{ id: 'op-1', kind: 'chat', startedCursor: '0' }],
+          cursor: '9',
+        }),
+      transcript: async () => [
+        { id: 'm1', role: 'assistant', content: 'A.', toolCalls: [call('c1')] },
+        { role: 'tool', toolCallId: 'c1', content: '1' },
+        { id: 'm2', role: 'assistant', content: 'B.', toolCalls: [call('c2')] },
+      ],
+    })
+    const think = (messageId: string) =>
+      ({
+        type: EventType.REASONING_MESSAGE_CONTENT,
+        messageId,
+        delta: `Think ${messageId}.`,
+      }) as const
+    const says = (messageId: string, delta: string) =>
+      ({ type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta }) as const
+    const started = (toolCallId: string) =>
+      ({
+        type: EventType.TOOL_CALL_START,
+        toolCallId,
+        toolCallName: 'list',
+      }) as const
+    const result = (toolCallId: string) =>
+      ({
+        type: EventType.TOOL_CALL_RESULT,
+        toolCallId,
+        messageId: 'x',
+        content: '1',
+      }) as const
+
+    stream.push(
+      entry(1, think('r1')),
+      entry(2, says('m1', 'A.')),
+      entry(3, started('c1')),
+      entry(4, result('c1')),
+    )
+    // A remote replay comes in chunks, with a macrotask between them.
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    stream.push(
+      entry(5, think('r2')),
+      entry(6, says('m2', 'B.')),
+      entry(7, started('c2')),
+      entry(10, result('c2')),
+      entry(11, think('r3')),
+      entry(12, says('m3', 'C.')),
+    )
+
+    await vi.waitFor(() => expect(assistantText(view)).toBe('A.B.C.'))
+    expect(view.store.get().messages.at(-1)).toMatchObject({
+      id: 'turn-op-1',
+      parts: [
+        { type: 'reasoning', text: 'Think r3.' },
+        { type: 'text', text: 'C.' },
+      ],
+    })
+  })
+
+  it('drops replayed reasoning of an attempt that a retry ends', async () => {
+    const { view, stream } = await openView({
+      snapshot: () =>
+        sessionSnapshot({
+          status: 'running',
+          activeOperations: [{ id: 'op-1', kind: 'chat', startedCursor: '0' }],
+          cursor: '3',
+        }),
+    })
+
+    stream.push(
+      entry(1, {
+        type: EventType.REASONING_MESSAGE_CONTENT,
+        messageId: 'r1',
+        delta: 'Lost.',
+      }),
+      entry(2, {
+        type: EventType.CUSTOM,
+        name: HARNESS_EVENTS.turnRetry,
+        value: { operationId: 'op-1', retries: 1, continued: false },
+      }),
+      entry(3, {
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm2',
+        delta: 'Answer.',
+      }),
+    )
+
+    await vi.waitFor(() => expect(assistantText(view)).toBe('Answer.'))
+    expect(view.store.get().messages).toMatchObject([
+      { parts: [{ type: 'text', text: 'Answer.' }] },
+    ])
+  })
+
+  it('replays only the operations that run', async () => {
+    const { view, stream } = await openView({
+      snapshot: () =>
+        sessionSnapshot({
+          activeOperations: [{ id: 'op-1', kind: 'agent', startedCursor: '0' }],
+          // A durable log counts records that are no events.
+          cursor: '9',
+        }),
+    })
+    const says = (messageId: string, delta: string) =>
+      ({ type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta }) as const
+
+    stream.push(
+      entry(1, says('m-old', 'Old turn.'), 'op-old'),
+      entry(2, says('m1', 'Still working.')),
+    )
+
+    await vi.waitFor(() => expect(assistantText(view)).toBe('Still working.'))
+  })
+
+  it('shows how a background child ended, from its saved card', async () => {
+    const call = (id: string) => ({
+      id,
+      type: 'function' as const,
+      function: { name: 'writer', arguments: '{}' },
+    })
+    const started = (toolCallId: string, subagentRunId: string) => ({
+      role: 'tool' as const,
+      toolCallId,
+      content: JSON.stringify({ subagentRunId, result: { status: 'started' } }),
+    })
+    const { view } = await openView({
+      transcript: async () => [
+        {
+          id: 'm1',
+          role: 'assistant',
+          content: null,
+          toolCalls: [call('c1'), call('c2')],
+        },
+        started('c1', 's1'),
+        started('c2', 's2'),
+      ],
+      agentTranscript: async (id) => [
+        {
+          role: 'assistant',
+          content: id === 's1' ? 'All done.' : '',
+          metadata: {
+            tanstack: {
+              subagent:
+                id === 's1'
+                  ? { name: 'writer', status: 'finished' }
+                  : { name: 'writer', status: 'error', placeholder: true },
+            },
+          },
+        },
+      ],
+    })
+
+    await vi.waitFor(() =>
+      expect(view.store.get().messages[0]).toMatchObject({
+        parts: [
+          { type: 'tool-call', id: 'c1' },
+          {
+            type: 'agent',
+            status: 'done',
+            parts: [{ type: 'text', text: 'All done.' }],
+          },
+          { type: 'tool-call', id: 'c2' },
+          // It failed before its first message: only its card is saved.
+          { type: 'agent', id: 's2', status: 'failed', parts: [] },
+        ],
+      }),
+    )
+  })
+
+  it('shows the later events of a background child that a saved message shows', async () => {
+    const { view, stream } = await openView({
+      transcript: async () => [
+        {
+          id: 'm1',
+          role: 'assistant',
+          content: null,
+          toolCalls: [
+            {
+              id: 'c1',
+              type: 'function',
+              function: { name: 'writer', arguments: '{}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          toolCallId: 'c1',
+          content: JSON.stringify({
+            subagentRunId: 's1',
+            result: { status: 'started' },
+          }),
+        },
+      ],
+      agentTranscript: async () => [
+        { role: 'assistant', content: 'Found one. ' },
+      ],
+      snapshot: () => sessionSnapshot({ cursor: '3' }),
+    })
+    const child = { subagentRunId: 's1' }
+
+    stream.push(
+      entry(4, {
+        ...child,
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'c',
+        delta: 'Found two.',
+      }),
+      entry(5, { ...child, type: EventType.SUBAGENT_FINISHED, result: 2 }),
+    )
+
+    await vi.waitFor(() =>
+      expect(view.store.get().messages[0]).toMatchObject({
+        parts: [
+          { type: 'tool-call', id: 'c1' },
+          {
+            type: 'agent',
+            id: 's1',
+            status: 'done',
+            result: 2,
+            parts: [{ type: 'text', text: 'Found one. Found two.' }],
+          },
+        ],
+      }),
+    )
+  })
+
+  it('fills the agent part of a saved agent call from its own messages', async () => {
+    const asked: Array<string> = []
+    const { view } = await openView({
+      transcript: async () => [
+        {
+          id: 'm1',
+          role: 'assistant',
+          content: null,
+          toolCalls: [
+            {
+              id: 'c1',
+              type: 'function',
+              function: { name: 'writer', arguments: '{"prompt":"Notes"}' },
+            },
+          ],
+        },
+        {
+          role: 'tool',
+          toolCallId: 'c1',
+          content: JSON.stringify({ subagentRunId: 's1', result: 'Note 1' }),
+        },
+      ],
+      agentTranscript: async (id) => {
+        asked.push(id)
+        return [
+          { role: 'user', content: 'Notes' },
+          { role: 'assistant', content: 'Note 1' },
+        ]
+      },
+    })
+
+    await vi.waitFor(() =>
+      expect(view.store.get().messages).toMatchObject([
+        {
+          role: 'assistant',
+          parts: [
+            { type: 'tool-call', id: 'c1', status: 'done' },
+            {
+              type: 'agent',
+              id: 's1',
+              name: 'writer',
+              status: 'done',
+              parts: [{ type: 'text', text: 'Note 1' }],
+            },
+          ],
+        },
+      ]),
+    )
+    expect(asked).toEqual(['s1'])
+  })
+
+  it('shows the usage, the models, and the settings, and reads the usage again after a model call', async () => {
+    const used = (calls: number) =>
+      sessionSnapshot({
+        usage: {
+          ...emptyUsage(),
+          total: { ...emptyUsage().total, calls },
+        },
+      })
+    const snapshot = vi.fn(() => used(2))
+    snapshot.mockReturnValueOnce(used(1))
+    const { view, stream } = await openView({
+      snapshot,
+      describe: () => ({
+        ...emptyDescription(),
+        models: ['fast', 'strong'],
+        settings: { model: 'strong' },
+      }),
+    })
+
+    expect(view.store.get()).toMatchObject({
+      usage: { total: { calls: 1 } },
+      models: ['fast', 'strong'],
+      settings: { model: 'strong' },
+    })
+    stream.push(custom(HARNESS_EVENTS.usage, { model: 'fast' }))
+
+    await vi.waitFor(() => expect(view.store.get().usage?.total.calls).toBe(2))
+  })
+})
+
+describe('session view dispose', () => {
+  it('can dispose twice', async () => {
+    const { view } = await openView()
+
+    view.dispose()
+    view.dispose()
+
+    expect(view.store.get().connection).toBe('closed')
+  })
+
+  const afterDispose: Array<{
+    action: string
+    act: (view: SessionView) => unknown
+  }> = [
+    { action: 'notice', act: (view) => view.notice('hi') },
+    { action: 'command', act: (view) => view.command('ping') },
+    {
+      action: 'setConfig',
+      act: (view) => view.setConfig({ key: 'mode', value: 'plan' }),
+    },
+    { action: 'cancel', act: (view) => view.cancel() },
+    { action: 'approveAll', act: (view) => view.approveAll() },
+    {
+      action: 'question.answer',
+      act: (view) => view.store.get().questions[0]?.answer('yes'),
+    },
+  ]
+
+  it.each(afterDispose)('$action throws after dispose', async ({ act }) => {
+    const { view, inputs } = await openView({
+      snapshot: () => sessionSnapshot({ pendingQuestions: [confirm] }),
+    })
+
+    view.dispose()
+
+    await expect(async () => act(view)).rejects.toThrow(
+      'The session view is disposed.',
+    )
+    expect(inputs).toEqual([])
+  })
+})
diff --git a/packages/ai-harness/tests/view-reduce.test.ts b/packages/ai-harness/tests/view-reduce.test.ts
new file mode 100644
index 0000000000..e3cf44ce6d
--- /dev/null
+++ b/packages/ai-harness/tests/view-reduce.test.ts
@@ -0,0 +1,1133 @@
+import { describe, expect, it } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { HARNESS_EVENTS } from '../src'
+import {
+  applyDescription,
+  applyEvent,
+  applySnapshot,
+  emptyState,
+  messagesFromTranscript,
+  withNotice,
+  withUserMessage,
+} from '../src/view/reduce'
+import { at, childRun, custom, sessionSnapshot } from './view-fixtures'
+import type { SessionEvent } from '../src'
+import type { WaitingInput } from '../src/types'
+import type { ItemFactory } from '../src/view/reduce'
+import type { SessionViewState } from '../src/view/types'
+
+const fold = (events: Array<SessionEvent>, start = emptyState()) =>
+  events.reduce(applyEvent, start)
+
+const factory: ItemFactory = {
+  approval: (interrupt, call) => ({
+    id: interrupt.id,
+    ...(interrupt.toolCallId ? { toolCallId: interrupt.toolCallId } : {}),
+    tool: call?.name ?? 'tool',
+    args: call?.args,
+    approve: () => {},
+    reject: () => {},
+  }),
+  clientTool: (interrupt, call) => ({
+    id: interrupt.id,
+    ...(interrupt.toolCallId ? { toolCallId: interrupt.toolCallId } : {}),
+    tool: call?.name ?? 'tool',
+    args: call?.args,
+    resolve: () => {},
+    fail: () => {},
+  }),
+  question: (question) => ({
+    id: question.questionId,
+    message: question.message,
+    answer: async () => ({ inputId: 'i', status: 'accepted' }),
+  }),
+  interrupt: (interrupt) => ({
+    id: interrupt.id,
+    reason: interrupt.reason,
+    resolve: () => {},
+    cancel: () => {},
+  }),
+  agent: (operation) => ({
+    ...operation,
+    send: async () => ({ inputId: 'i', status: 'accepted' }),
+    cancel: async () => ({ inputId: 'i', status: 'accepted' }),
+  }),
+}
+
+function assistantParts(state: SessionViewState) {
+  const message = state.messages.find((item) => item.role === 'assistant')
+  return message?.role === 'assistant' ? message.parts : []
+}
+
+describe('view reducer', () => {
+  it('streams text and reasoning into one assistant message per turn', () => {
+    const state = fold([
+      at({
+        type: EventType.REASONING_MESSAGE_CONTENT,
+        messageId: 'r',
+        delta: 'Think',
+      }),
+      at({
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm',
+        delta: 'Hel',
+      }),
+      at({ type: EventType.TEXT_MESSAGE_CONTENT, messageId: 'm', delta: 'lo' }),
+      at(
+        {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId: 'n',
+          delta: 'Next turn',
+        },
+        'op-2',
+      ),
+    ])
+    expect(state.messages).toEqual([
+      {
+        id: 'turn-op-1',
+        role: 'assistant',
+        parts: [
+          { type: 'reasoning', text: 'Think' },
+          { type: 'text', text: 'Hello' },
+        ],
+      },
+      {
+        id: 'turn-op-2',
+        role: 'assistant',
+        parts: [{ type: 'text', text: 'Next turn' }],
+      },
+    ])
+  })
+
+  it('builds tool calls from start, args, end, and a result in a later turn', () => {
+    const state = fold([
+      at({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c1',
+        toolCallName: 'remove',
+      }),
+      at({
+        type: EventType.TOOL_CALL_ARGS,
+        toolCallId: 'c1',
+        delta: '{"path":',
+      }),
+      at({
+        type: EventType.TOOL_CALL_ARGS,
+        toolCallId: 'c1',
+        delta: '"a.txt"}',
+      }),
+      at({ type: EventType.TOOL_CALL_END, toolCallId: 'c1' }),
+      // The approved call finishes in the next turn.
+      at(
+        {
+          type: EventType.TOOL_CALL_RESULT,
+          toolCallId: 'c1',
+          messageId: 'x',
+          content: '"removed"',
+        },
+        'op-2',
+      ),
+    ])
+    expect(state.messages).toHaveLength(1)
+    expect(assistantParts(state)).toEqual([
+      {
+        type: 'tool-call',
+        id: 'c1',
+        name: 'remove',
+        argsText: '{"path":"a.txt"}',
+        args: { path: 'a.txt' },
+        status: 'done',
+        result: 'removed',
+      },
+    ])
+  })
+
+  it('takes the parsed input of an end with no args, and marks a failed result', () => {
+    const state = fold([
+      at({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c1',
+        toolCallName: 'search',
+      }),
+      at({ type: EventType.TOOL_CALL_END, toolCallId: 'c1', input: { q: 1 } }),
+      at({
+        type: EventType.TOOL_CALL_RESULT,
+        toolCallId: 'c1',
+        messageId: 'x',
+        content: '{"error":"down"}',
+        metadata: { tanstack: { state: 'output-error' } },
+      }),
+    ])
+    expect(assistantParts(state)).toMatchObject([
+      { id: 'c1', args: { q: 1 }, status: 'failed' },
+    ])
+  })
+
+  it('ignores a tool result it has no call for', () => {
+    const start = emptyState()
+    const state = fold(
+      [
+        at({
+          type: EventType.TOOL_CALL_RESULT,
+          toolCallId: 'ghost',
+          messageId: 'x',
+          content: '1',
+        }),
+      ],
+      start,
+    )
+    expect(state).toBe(start)
+  })
+
+  it('nests child agents with their own text and tool calls', () => {
+    const child = { subagentRunId: 'child-1' }
+    const state = fold([
+      at({
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm',
+        delta: 'Asking a helper.',
+      }),
+      at({ ...child, type: EventType.SUBAGENT_STARTED, name: 'claude_code' }),
+      at({
+        ...child,
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'c',
+        delta: 'Done',
+      }),
+      at({
+        ...child,
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 't1',
+        toolCallName: 'Edit',
+      }),
+      at({
+        subagentRunId: 'grand-1',
+        type: EventType.SUBAGENT_STARTED,
+        name: 'inner',
+        parentSubagentRunId: 'child-1',
+      }),
+      at({
+        subagentRunId: 'grand-1',
+        type: EventType.SUBAGENT_ERROR,
+        message: 'no key',
+      }),
+      at({ ...child, type: EventType.SUBAGENT_FINISHED }),
+    ])
+    const [lead, agent] = assistantParts(state)
+    expect(lead).toEqual({ type: 'text', text: 'Asking a helper.' })
+    expect(agent).toMatchObject({
+      type: 'agent',
+      id: 'child-1',
+      name: 'claude_code',
+      status: 'done',
+      parts: [
+        { type: 'text', text: 'Done' },
+        { type: 'tool-call', id: 't1', name: 'Edit', status: 'running' },
+        {
+          type: 'agent',
+          id: 'grand-1',
+          name: 'inner',
+          status: 'failed',
+          error: 'no key',
+          parts: [],
+        },
+      ],
+    })
+  })
+
+  it('a child that starts first gets its own assistant message', () => {
+    const state = fold([
+      at({
+        subagentRunId: 'child-1',
+        type: EventType.SUBAGENT_STARTED,
+        name: 'codex',
+      }),
+    ])
+    expect(state.messages).toEqual([
+      {
+        id: 'turn-op-1',
+        role: 'assistant',
+        parts: [
+          {
+            type: 'agent',
+            id: 'child-1',
+            name: 'codex',
+            status: 'running',
+            parts: [],
+          },
+        ],
+      },
+    ])
+  })
+
+  it('adds notices for errors, resumes, command text, and rejected inputs', () => {
+    const state = fold([
+      at({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c1',
+        toolCallName: 'slow',
+      }),
+      at({ type: EventType.RUN_ERROR, message: 'boom' }),
+      custom(HARNESS_EVENTS.operationResumed, {}),
+      at(
+        {
+          type: EventType.CUSTOM,
+          name: 'harness.command.result',
+          value: { name: 'goal', result: 'Goal: x' },
+        },
+        'op-c',
+      ),
+      at(
+        {
+          type: EventType.CUSTOM,
+          name: 'harness.command.result',
+          value: { name: 'stats', result: { ok: true } },
+        },
+        'op-d',
+      ),
+      custom(HARNESS_EVENTS.inputRejected, { inputId: 'i', reason: 'busy' }),
+      custom(HARNESS_EVENTS.inputRejected, { inputId: 'j' }),
+    ])
+    expect(state.messages.filter((item) => item.role === 'notice')).toEqual([
+      { id: 'notice-1', role: 'notice', kind: 'error', text: 'Error: boom' },
+      {
+        id: 'notice-2',
+        role: 'notice',
+        kind: 'info',
+        text: 'Resumed a turn that a crash stopped.',
+      },
+      { id: 'notice-3', role: 'notice', kind: 'command', text: 'Goal: x' },
+      {
+        id: 'notice-4',
+        role: 'notice',
+        kind: 'rejected',
+        text: 'Not accepted: busy',
+      },
+      {
+        id: 'notice-5',
+        role: 'notice',
+        kind: 'rejected',
+        text: 'Not accepted: unknown reason',
+      },
+    ])
+    expect(assistantParts(state)[0]).toMatchObject({ status: 'failed' })
+  })
+
+  it('keeps sign-ins per connector and clears them when a chat turn starts', () => {
+    const signedOut = fold([
+      custom(HARNESS_EVENTS.authRequired, {
+        connector: 'notion',
+        url: 'https://a',
+      }),
+      custom(HARNESS_EVENTS.authRequired, {
+        connector: 'notion',
+        url: 'https://b',
+        userCode: 'X1',
+      }),
+      custom(HARNESS_EVENTS.authRequired, { connector: 'github' }),
+    ])
+    expect(signedOut.signIns).toEqual([
+      { connector: 'notion', url: 'https://b', userCode: 'X1' },
+      { connector: 'github' },
+    ])
+    const next = applyEvent(
+      signedOut,
+      custom(HARNESS_EVENTS.operationStarted, {
+        operationId: 'op-9',
+        kind: 'chat',
+      }),
+    )
+    expect(next.signIns).toEqual([])
+  })
+
+  it('clears the sign-in of a connector when its connect command ends', () => {
+    const connected = fold([
+      custom(HARNESS_EVENTS.authRequired, {
+        connector: 'notion',
+        url: 'https://a',
+      }),
+      custom(HARNESS_EVENTS.authRequired, {
+        connector: 'linear',
+        url: 'https://b',
+      }),
+      custom('harness.command.result', {
+        name: 'connect:notion',
+        result: 'Connected to Notion.',
+      }),
+    ])
+    expect(connected.signIns).toEqual([
+      { connector: 'linear', url: 'https://b' },
+    ])
+    expect(connected.messages.at(-1)).toMatchObject({
+      role: 'notice',
+      kind: 'command',
+      text: 'Connected to Notion.',
+    })
+  })
+
+  it('follows plugin state and config values', () => {
+    const described = applyDescription(emptyState(), {
+      commands: [],
+      tools: [],
+      config: [
+        {
+          key: 'mode',
+          owner: 'p',
+          value: 'build',
+          option: { type: 'text', default: 'build' },
+        },
+      ],
+    })
+    const state = fold(
+      [
+        at(
+          {
+            type: EventType.STATE_SNAPSHOT,
+            snapshot: { plugins: { 'tanstack/goal': { round: 2 } } },
+          },
+          'session',
+        ),
+        custom(HARNESS_EVENTS.configChanged, { key: 'mode', value: 'plan' }),
+      ],
+      described,
+    )
+    expect(state.plugins).toEqual({ 'tanstack/goal': { round: 2 } })
+    expect(state.config[0]?.value).toBe('plan')
+  })
+
+  it('reads status, approvals, questions, and agents from the snapshot, and keeps item identity', () => {
+    const withCall = fold([
+      at({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c1',
+        toolCallName: 'remove',
+      }),
+      at({ type: EventType.TOOL_CALL_ARGS, toolCallId: 'c1', delta: '{}' }),
+      at({ type: EventType.TOOL_CALL_END, toolCallId: 'c1' }),
+    ])
+    const waiting = sessionSnapshot({
+      status: 'requires_action',
+      pendingInterrupts: [
+        { id: 'int-1', reason: 'tool_approval', toolCallId: 'c1' },
+      ],
+      pendingQuestions: [{ questionId: 'q1', message: 'Sure?' }],
+      activeOperations: [{ id: 'op-a', kind: 'agent', agent: 'pricer' }],
+      queuedTurns: 1,
+      plugins: { p: 1 },
+    })
+    const first = applySnapshot(withCall, waiting, factory, { initial: true })
+    expect(first.status).toBe('requires_action')
+    expect(first.queuedTurns).toBe(1)
+    expect(first.approvals).toMatchObject([
+      { id: 'int-1', tool: 'remove', args: {} },
+    ])
+    expect(first.questions).toMatchObject([{ id: 'q1', message: 'Sure?' }])
+    expect(first.agents).toMatchObject([{ id: 'op-a', name: 'pricer' }])
+    expect(first.plugins).toEqual({ p: 1 })
+    expect(assistantParts(first)[0]).toMatchObject({ status: 'needs-approval' })
+
+    const again = applySnapshot(
+      first,
+      { ...waiting, plugins: { p: 2 } },
+      factory,
+    )
+    expect(again).toBe(first)
+  })
+
+  it('reads the waiting inputs from the snapshot, and keeps their identity', () => {
+    // Each snapshot gets a new copy, as one from the session does.
+    const later: WaitingInput = {
+      inputId: 'in-1',
+      delivery: 'queue',
+      message: 'later',
+    }
+    const first = applySnapshot(
+      emptyState(),
+      sessionSnapshot({ waitingInputs: [{ ...later }] }),
+      factory,
+    )
+    expect(first.waitingInputs).toEqual([
+      { inputId: 'in-1', delivery: 'queue', message: 'later' },
+    ])
+    expect(
+      applySnapshot(
+        first,
+        sessionSnapshot({ waitingInputs: [{ ...later }] }),
+        factory,
+      ),
+    ).toBe(first)
+
+    const moved = applySnapshot(
+      first,
+      sessionSnapshot({ waitingInputs: [{ ...later, delivery: 'steer' }] }),
+      factory,
+    )
+    expect(moved.waitingInputs).toEqual([
+      { inputId: 'in-1', delivery: 'steer', message: 'later' },
+    ])
+    // A snapshot without the list has no waiting inputs.
+    expect(
+      applySnapshot(moved, sessionSnapshot(), factory).waitingInputs,
+    ).toEqual([])
+  })
+
+  it('reads a client tool interrupt as a client tool, not an approval', () => {
+    const withCall = fold([
+      at({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c1',
+        toolCallName: 'openScreen',
+      }),
+      at({ type: EventType.TOOL_CALL_END, toolCallId: 'c1' }),
+    ])
+    const waiting = sessionSnapshot({
+      status: 'requires_action',
+      pendingInterrupts: [
+        {
+          id: 'client_tool_c1',
+          reason: 'tanstack:client_tool_execution',
+          toolCallId: 'c1',
+          metadata: {
+            'tanstack:interruptBinding': {
+              v: 1,
+              kind: 'client-tool-execution',
+              interruptId: 'client_tool_c1',
+              toolName: 'openScreen',
+              toolCallId: 'c1',
+              outputSchemaHash: 'out',
+              responseSchemaHash: 'response',
+            },
+          },
+        },
+      ],
+    })
+    const first = applySnapshot(withCall, waiting, factory)
+    expect(first.approvals).toEqual([])
+    expect(first.clientTools).toMatchObject([
+      { id: 'client_tool_c1', toolCallId: 'c1', tool: 'openScreen' },
+    ])
+    // The call runs in the UI. It does not wait for a yes or no.
+    expect(assistantParts(first)[0]).toMatchObject({ status: 'running' })
+    expect(applySnapshot(first, waiting, factory)).toBe(first)
+  })
+
+  it('reads a sign-in interrupt as a sign-in, not an approval', () => {
+    const waiting = sessionSnapshot({
+      status: 'requires_action',
+      pendingInterrupts: [
+        {
+          id: 'mcp_input_c1',
+          reason: 'auth_required',
+          toolCallId: 'c1',
+          metadata: {
+            'tanstack:interruptPayload': {
+              kind: 'form',
+              request: { connector: 'github', url: 'https://example.test/a' },
+            },
+          },
+        },
+      ],
+    })
+    const first = applySnapshot(emptyState(), waiting, factory)
+    expect(first.approvals).toEqual([])
+    expect(first.signIns).toEqual([
+      { connector: 'github', url: 'https://example.test/a' },
+    ])
+    expect(applySnapshot(first, waiting, factory)).toBe(first)
+  })
+
+  it('hides the continue note of a retry after a reload', () => {
+    const messages = messagesFromTranscript([
+      { role: 'user', content: 'hi' },
+      { role: 'assistant', content: 'Part one' },
+      {
+        role: 'user',
+        content: 'Continue.',
+        metadata: { tanstack: { synthetic: true } },
+      },
+    ])
+    expect(messages.map((message) => message.role)).toEqual([
+      'user',
+      'assistant',
+    ])
+  })
+
+  it('builds messages from a saved transcript', () => {
+    const messages = messagesFromTranscript([
+      { role: 'user', content: 'hi' },
+      {
+        role: 'assistant',
+        content: 'Checking.',
+        thinking: [{ content: 'plan' }],
+        toolCalls: [
+          {
+            id: 'c1',
+            type: 'function',
+            function: { name: 'read', arguments: '{"a":1}' },
+          },
+        ],
+      },
+      { role: 'tool', content: '"file text"', toolCallId: 'c1' },
+    ])
+    expect(messages).toEqual([
+      { id: 'history-0', role: 'user', text: 'hi' },
+      {
+        id: 'history-1',
+        role: 'assistant',
+        parts: [
+          { type: 'reasoning', text: 'plan' },
+          { type: 'text', text: 'Checking.' },
+          {
+            type: 'tool-call',
+            id: 'c1',
+            name: 'read',
+            argsText: '{"a":1}',
+            args: { a: 1 },
+            status: 'done',
+            result: 'file text',
+          },
+        ],
+      },
+    ])
+  })
+
+  it('numbers notices by position', () => {
+    const state = withNotice(withNotice(emptyState(), 'ui', 'a'), 'ui', 'b')
+    expect(state.messages.map((item) => item.id)).toEqual([
+      'notice-0',
+      'notice-1',
+    ])
+  })
+
+  // A user message, then a turn with text, a tool call, and a child agent.
+  const placed = fold(
+    [
+      at({ type: EventType.TEXT_MESSAGE_CONTENT, messageId: 'm', delta: 'Hi' }),
+      at({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c1',
+        toolCallName: 'read',
+      }),
+      at({
+        subagentRunId: 'child-1',
+        type: EventType.SUBAGENT_STARTED,
+        name: 'helper',
+      }),
+    ],
+    withUserMessage(emptyState(), 'hi'),
+  )
+  const unchanged: Array<[string, SessionEvent]> = [
+    [
+      'an empty delta',
+      at({ type: EventType.TEXT_MESSAGE_CONTENT, messageId: 'm', delta: '' }),
+    ],
+    [
+      'an empty delta of a child',
+      at({
+        subagentRunId: 'child-1',
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'c',
+        delta: '',
+      }),
+    ],
+    [
+      'text of a child it does not know',
+      at({
+        subagentRunId: 'ghost',
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'g',
+        delta: 'boo',
+      }),
+    ],
+    [
+      'a tool call start that repeats an id',
+      at({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c1',
+        toolCallName: 'read',
+      }),
+    ],
+    [
+      'args of a tool call it does not know',
+      at({ type: EventType.TOOL_CALL_ARGS, toolCallId: 'ghost', delta: '{}' }),
+    ],
+    [
+      'a result of a tool call it does not know',
+      at({
+        type: EventType.TOOL_CALL_RESULT,
+        toolCallId: 'ghost',
+        messageId: 'x',
+        content: '1',
+      }),
+    ],
+    [
+      'a child start that repeats an id',
+      at({
+        subagentRunId: 'child-1',
+        type: EventType.SUBAGENT_STARTED,
+        name: 'helper',
+      }),
+    ],
+    ['a run error of a child', at(childRun.error)],
+    [
+      'a state snapshot without plugins',
+      at({ type: EventType.STATE_SNAPSHOT, snapshot: { other: 1 } }, 'session'),
+    ],
+    [
+      'an event it does not show',
+      at({ type: EventType.RUN_STARTED, threadId: 't', runId: 'r' }),
+    ],
+    [
+      'a config change for a key it does not know',
+      custom(HARNESS_EVENTS.configChanged, { key: 'ghost', value: 1 }),
+    ],
+    [
+      'a config change without a key',
+      custom(HARNESS_EVENTS.configChanged, { value: 1 }),
+    ],
+    [
+      'a command result with no text',
+      custom('harness.command.result', { name: 'stats', result: '' }),
+    ],
+    [
+      'a sign-in request without a connector',
+      custom(HARNESS_EVENTS.authRequired, { url: 'https://a' }),
+    ],
+    [
+      'a chat start with no sign-ins',
+      custom(HARNESS_EVENTS.operationStarted, {
+        operationId: 'op-2',
+        kind: 'chat',
+      }),
+    ],
+    ['a custom event it does not know', custom('app.unknown', null)],
+  ]
+
+  it.each(unchanged)('returns the same state for %s', (_name, entry) => {
+    expect(applyEvent(placed, entry)).toBe(placed)
+  })
+
+  it('routes child events to the right agent among nested and sibling agents', () => {
+    const state = fold([
+      at({
+        subagentRunId: 'child-1',
+        type: EventType.SUBAGENT_STARTED,
+        name: 'helper',
+      }),
+      at({
+        subagentRunId: 'grand-1',
+        type: EventType.SUBAGENT_STARTED,
+        name: 'inner',
+        parentSubagentRunId: 'child-1',
+      }),
+      at({
+        subagentRunId: 'child-2',
+        type: EventType.SUBAGENT_STARTED,
+        name: 'fixer',
+      }),
+      // Its parent is unknown, so it goes to the top level.
+      at({
+        subagentRunId: 'child-3',
+        type: EventType.SUBAGENT_STARTED,
+        name: 'lost',
+        parentSubagentRunId: 'ghost',
+      }),
+      at({
+        subagentRunId: 'child-2',
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'c2',
+        delta: 'two',
+      }),
+      at({
+        subagentRunId: 'grand-1',
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'g1',
+        delta: 'inner',
+      }),
+      at({
+        subagentRunId: 'child-2',
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 't2',
+        toolCallName: 'Edit',
+      }),
+      at({
+        subagentRunId: 'child-2',
+        type: EventType.TOOL_CALL_RESULT,
+        toolCallId: 't2',
+        messageId: 'r2',
+        content: '{"ok":true}',
+      }),
+    ])
+    expect(assistantParts(state)).toEqual([
+      {
+        type: 'agent',
+        id: 'child-1',
+        name: 'helper',
+        status: 'running',
+        parts: [
+          {
+            type: 'agent',
+            id: 'grand-1',
+            name: 'inner',
+            status: 'running',
+            parts: [{ type: 'text', text: 'inner' }],
+          },
+        ],
+      },
+      {
+        type: 'agent',
+        id: 'child-2',
+        name: 'fixer',
+        status: 'running',
+        parts: [
+          { type: 'text', text: 'two' },
+          {
+            type: 'tool-call',
+            id: 't2',
+            name: 'Edit',
+            argsText: '',
+            args: undefined,
+            status: 'done',
+            result: { ok: true },
+          },
+        ],
+      },
+      {
+        type: 'agent',
+        id: 'child-3',
+        name: 'lost',
+        status: 'running',
+        parts: [],
+      },
+    ])
+  })
+
+  it('keeps content parts of a tool result, and text that is not JSON', () => {
+    const state = fold([
+      at({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c1',
+        toolCallName: 'shot',
+      }),
+      at({
+        type: EventType.TOOL_CALL_RESULT,
+        toolCallId: 'c1',
+        messageId: 'r1',
+        content: [{ type: 'text', text: 'see the image' }],
+      }),
+      at({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c2',
+        toolCallName: 'say',
+      }),
+      at({ type: EventType.TOOL_CALL_ARGS, toolCallId: 'c2', delta: 'loud' }),
+      at({ type: EventType.TOOL_CALL_END, toolCallId: 'c2' }),
+      at({
+        type: EventType.TOOL_CALL_RESULT,
+        toolCallId: 'c2',
+        messageId: 'r2',
+        content: 'plain words',
+      }),
+    ])
+    expect(assistantParts(state)).toEqual([
+      {
+        type: 'tool-call',
+        id: 'c1',
+        name: 'shot',
+        argsText: '',
+        args: undefined,
+        status: 'done',
+        result: [{ type: 'text', text: 'see the image' }],
+      },
+      {
+        type: 'tool-call',
+        id: 'c2',
+        name: 'say',
+        argsText: 'loud',
+        args: 'loud',
+        status: 'done',
+        result: 'plain words',
+      },
+    ])
+  })
+
+  it('marks only running tool calls as failed on a run error', () => {
+    const state = fold([
+      at({
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: 'm',
+        delta: 'Trying.',
+      }),
+      at({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c1',
+        toolCallName: 'read',
+      }),
+      at({
+        type: EventType.TOOL_CALL_RESULT,
+        toolCallId: 'c1',
+        messageId: 'r',
+        content: '"ok"',
+      }),
+      at({
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c2',
+        toolCallName: 'write',
+      }),
+      at({ type: EventType.RUN_ERROR, message: 'boom' }),
+    ])
+    expect(
+      assistantParts(state).map((part) =>
+        part.type === 'tool-call' ? `${part.id}:${part.status}` : part.type,
+      ),
+    ).toEqual(['text', 'c1:done', 'c2:failed'])
+  })
+
+  it('adds only a notice for a run error with no running tool call', () => {
+    const state = fold([at({ type: EventType.RUN_ERROR, message: 'boom' })])
+    expect(state.messages).toEqual([
+      { id: 'notice-0', role: 'notice', kind: 'error', text: 'Error: boom' },
+    ])
+  })
+
+  it('finds tool calls in earlier turns, names unnamed agents, and skips other operations', () => {
+    const turns = fold(
+      [
+        at({
+          type: EventType.TOOL_CALL_START,
+          toolCallId: 'c1',
+          toolCallName: 'read',
+        }),
+        at(
+          {
+            type: EventType.TEXT_MESSAGE_CONTENT,
+            messageId: 'n',
+            delta: 'Next.',
+          },
+          'op-2',
+        ),
+      ],
+      withUserMessage(emptyState(), 'hi'),
+    )
+    const state = applySnapshot(
+      turns,
+      sessionSnapshot({
+        pendingInterrupts: [
+          { id: 'i1', reason: 'tool_approval', toolCallId: 'c1' },
+          { id: 'i2', reason: 'tool_approval', toolCallId: 'ghost' },
+          { id: 'i3', reason: 'confirm' },
+        ],
+        activeOperations: [
+          { id: 'op-a', kind: 'agent' },
+          { id: 'op-c', kind: 'chat' },
+        ],
+      }),
+      factory,
+    )
+    expect(state.approvals.map((item) => item.tool)).toEqual([
+      'read',
+      'tool',
+      'tool',
+    ])
+    expect(state.agents).toMatchObject([{ id: 'op-a', name: 'agent' }])
+    expect(state.messages[1]).toMatchObject({
+      parts: [{ id: 'c1', status: 'needs-approval' }],
+    })
+    expect(state.messages[0]).toBe(turns.messages[0])
+    expect(state.messages[2]).toBe(turns.messages[2])
+  })
+
+  it('builds transcript messages from content parts, saved ids, and failed tool results', () => {
+    const messages = messagesFromTranscript([
+      {
+        id: 'saved-1',
+        role: 'user',
+        content: [
+          { type: 'text', content: 'Look at ' },
+          {
+            type: 'image',
+            source: { type: 'url', value: 'https://example.com/a.png' },
+          },
+          { type: 'text', content: 'this.' },
+        ],
+      },
+      {
+        role: 'assistant',
+        content: null,
+        toolCalls: [
+          {
+            id: 'c1',
+            type: 'function',
+            function: { name: 'read', arguments: 'not json' },
+          },
+        ],
+      },
+      {
+        role: 'tool',
+        content: 'no such file',
+        toolCallId: 'c1',
+        error: 'ENOENT',
+      },
+      // A result whose call is not in the transcript.
+      { role: 'tool', content: 'orphan', toolCallId: 'ghost' },
+      { role: 'assistant', content: '' },
+    ])
+    expect(messages).toEqual([
+      { id: 'saved-1', role: 'user', text: 'Look at this.' },
+      {
+        id: 'history-1',
+        role: 'assistant',
+        parts: [
+          {
+            type: 'tool-call',
+            id: 'c1',
+            name: 'read',
+            argsText: 'not json',
+            args: 'not json',
+            status: 'failed',
+            result: 'no such file',
+          },
+        ],
+      },
+      { id: 'history-4', role: 'assistant', parts: [] },
+    ])
+  })
+
+  it('keeps the result of a child agent', () => {
+    const child = { subagentRunId: 'child-1' }
+    const state = fold([
+      at({ ...child, type: EventType.SUBAGENT_STARTED, name: 'pricer' }),
+      at({
+        ...child,
+        type: EventType.SUBAGENT_FINISHED,
+        result: { price: 12 },
+      }),
+    ])
+
+    expect(assistantParts(state)).toMatchObject([
+      { type: 'agent', status: 'done', result: { price: 12 } },
+    ])
+  })
+
+  it('drops the text of a failed attempt on a retry, and keeps it when the model continues', () => {
+    const called = at({
+      type: EventType.TOOL_CALL_START,
+      toolCallId: 'c1',
+      toolCallName: 'list',
+    })
+    const ended = at({
+      type: EventType.TOOL_CALL_RESULT,
+      toolCallId: 'c1',
+      messageId: 'x',
+      content: '[]',
+    })
+    const partial = at({
+      type: EventType.TEXT_MESSAGE_CONTENT,
+      messageId: 'm',
+      delta: 'Half an ans',
+    })
+    const retry = (continued: boolean) =>
+      at({
+        type: EventType.CUSTOM,
+        name: HARNESS_EVENTS.turnRetry,
+        value: { operationId: 'op-1', retries: 1, continued },
+      })
+
+    const again = fold([called, ended, partial, retry(false)])
+    const continued = fold([called, ended, partial, retry(true)])
+
+    expect(assistantParts(again)).toMatchObject([
+      { type: 'tool-call', id: 'c1', status: 'done' },
+    ])
+    expect(assistantParts(continued)).toHaveLength(2)
+  })
+
+  it('keeps the text of an earlier model call on a retry', () => {
+    const start = (messageId: string) =>
+      at({ type: EventType.TEXT_MESSAGE_START, messageId, role: 'assistant' })
+    const says = (messageId: string, delta: string) =>
+      at({ type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta })
+
+    const state = fold([
+      start('m1'),
+      says('m1', 'One.'),
+      // A steer joined, so a second model call runs. It fails.
+      start('m2'),
+      says('m2', 'Tw'),
+      at({
+        type: EventType.CUSTOM,
+        name: HARNESS_EVENTS.turnRetry,
+        value: { operationId: 'op-1', retries: 1, continued: false },
+      }),
+    ])
+
+    expect(assistantParts(state)).toEqual([{ type: 'text', text: 'One.' }])
+  })
+
+  it('finds the call of an approval inside a child agent, and marks it', () => {
+    const child = { subagentRunId: 'child-1' }
+    const state = fold([
+      at({ ...child, type: EventType.SUBAGENT_STARTED, name: 'cleaner' }),
+      at({
+        ...child,
+        type: EventType.TOOL_CALL_START,
+        toolCallId: 'c2',
+        toolCallName: 'remove',
+      }),
+      at({
+        ...child,
+        type: EventType.TOOL_CALL_ARGS,
+        toolCallId: 'c2',
+        delta: '{"path":"a.txt"}',
+      }),
+      at({ ...child, type: EventType.TOOL_CALL_END, toolCallId: 'c2' }),
+    ])
+    const waiting = sessionSnapshot({
+      status: 'requires_action',
+      pendingInterrupts: [
+        { id: 'i1', reason: 'tool_call', toolCallId: 'c2', ...child },
+      ],
+    })
+
+    const next = applySnapshot(state, waiting, factory)
+
+    expect(next.approvals).toMatchObject([
+      { id: 'i1', tool: 'remove', args: { path: 'a.txt' } },
+    ])
+    expect(assistantParts(next)).toMatchObject([
+      { type: 'agent', parts: [{ id: 'c2', status: 'needs-approval' }] },
+    ])
+  })
+
+  it('adds an agent part after a saved agent call, failed when the child failed', () => {
+    const call = (id: string) => ({
+      id,
+      type: 'function' as const,
+      function: { name: 'writer', arguments: '{}' },
+    })
+    const messages = messagesFromTranscript([
+      { role: 'assistant', content: null, toolCalls: [call('c1'), call('c2')] },
+      {
+        role: 'tool',
+        toolCallId: 'c1',
+        content: JSON.stringify({ subagentRunId: 's1', result: 'ok' }),
+      },
+      {
+        role: 'tool',
+        toolCallId: 'c2',
+        content: JSON.stringify({ subagentRunId: 's2', error: 'no key' }),
+      },
+    ])
+
+    expect(messages).toMatchObject([
+      {
+        parts: [
+          { type: 'tool-call', id: 'c1' },
+          { type: 'agent', id: 's1', status: 'done', parts: [] },
+          { type: 'tool-call', id: 'c2' },
+          { type: 'agent', id: 's2', status: 'failed', error: 'no key' },
+        ],
+      },
+    ])
+  })
+})
diff --git a/packages/ai-harness/tests/view.test.ts b/packages/ai-harness/tests/view.test.ts
new file mode 100644
index 0000000000..0fe18b7fcb
--- /dev/null
+++ b/packages/ai-harness/tests/view.test.ts
@@ -0,0 +1,510 @@
+import { describe, expect, it, vi } from 'vitest'
+import { defineAgent, toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  createHarnessHandler,
+  createHarnessHost,
+  createPluginEvent,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '../src'
+import { createHarnessClient } from '../src/client'
+import { createSessionView } from '../src/view'
+import { after, gate, mockAdapter, text, toolCall } from './helpers'
+import type { Reply } from './helpers'
+import type { SessionViewSource } from '../src/view'
+
+const Pinged = createPluginEvent<{ count: number }>('test/pinged')
+
+const pinger = definePlugin({
+  name: 'test/pinger',
+  setup: (ctx) => {
+    const state = ctx.state({ pings: 0 })
+    return {
+      commands: {
+        ping: defineCommand({
+          description: 'Ping',
+          run: async () => {
+            const next = await state.update((saved) => ({
+              pings: saved.pings + 1,
+            }))
+            ctx.emit(Pinged, { count: next.pings })
+            return 'pong'
+          },
+        }),
+      },
+    }
+  },
+})
+
+const remove = toolDefinition({
+  name: 'remove',
+  description: 'Remove',
+  needsApproval: true,
+}).server(async () => 'removed')
+const archive = toolDefinition({
+  name: 'archive',
+  description: 'Archive',
+  needsApproval: true,
+}).server(async () => 'archived')
+
+async function open(replies: Array<Reply>, persistence = memoryPersistence()) {
+  const main = mockAdapter(replies)
+  const harness = defineHarness({
+    name: 'test/view',
+    adapter: main.adapter,
+    tools: [remove, archive],
+    plugins: () => [pinger],
+  })
+  const host = createHarnessHost({ persistence })
+  const session = await host.open(harness, { threadId: 't' })
+  return { host, session, harness, persistence, calls: main.calls }
+}
+
+/** A session with a view on it that has read the session once. */
+async function openView(replies: Array<Reply>) {
+  const opened = await open(replies)
+  const view = createSessionView(opened.session)
+  await view.ready
+  return { ...opened, view }
+}
+
+describe('createSessionView', () => {
+  it('streams a prompt into messages and ends the turn', async () => {
+    const { host, view } = await openView([() => text('Hello there.')])
+    const turnEnds: Array<string> = []
+    view.on('turnEnd', (value) => turnEnds.push(value.operationId))
+
+    await view.send('hi')
+
+    await vi.waitFor(() => expect(turnEnds).toHaveLength(1))
+    const { messages, status } = view.store.get()
+    expect(messages[0]).toMatchObject({ role: 'user', text: 'hi' })
+    expect(messages[1]).toMatchObject({
+      role: 'assistant',
+      parts: [{ type: 'text', text: 'Hello there.' }],
+    })
+    expect(status).toBe('idle')
+    view.dispose()
+    await host.close()
+  })
+
+  it('ignores an empty line', async () => {
+    const { host, view, calls } = await openView([])
+
+    await view.send('   ')
+
+    expect(view.store.get().messages).toEqual([])
+    expect(calls).toHaveLength(0)
+    view.dispose()
+    await host.close()
+  })
+
+  it('steers a running turn instead of starting a new one', async () => {
+    const hold = gate()
+    const { host, session, view, calls } = await openView([
+      after(hold.opened, 'first'),
+    ])
+    await view.send('start')
+    await vi.waitFor(() => expect(view.store.get().status).toBe('running'))
+    const steer = vi.spyOn(session, 'steer')
+
+    await view.send('faster')
+    hold.open()
+
+    expect(steer).toHaveBeenCalledWith('faster')
+    await vi.waitFor(() => expect(view.store.get().status).toBe('idle'))
+    expect(calls.length).toBeGreaterThanOrEqual(1)
+    view.dispose()
+    await host.close()
+  })
+
+  it('sends one resolve for two approvals, and ignores a second click', async () => {
+    const { host, session, view } = await openView([
+      () => [
+        ...toolCall('remove', {}, 'c1').slice(0, -1),
+        ...toolCall('archive', {}, 'c2').slice(1),
+      ],
+      () => text('Both done.'),
+    ])
+    const asked: Array<string> = []
+    view.on('approval', (approval) => asked.push(approval.tool))
+    const resolve = vi.spyOn(session, 'resolve')
+
+    await view.send('clean up')
+    await vi.waitFor(() => expect(view.store.get().approvals).toHaveLength(2))
+    expect(asked.sort()).toEqual(['archive', 'remove'])
+    const [first, second] = view.store.get().approvals
+    first?.approve()
+    first?.approve()
+    expect(resolve).not.toHaveBeenCalled()
+    second?.reject()
+
+    expect(resolve).toHaveBeenCalledTimes(1)
+    expect(resolve.mock.calls[0]?.[0]).toEqual([
+      { interruptId: first?.id, status: 'resolved', payload: true },
+      { interruptId: second?.id, status: 'resolved', payload: false },
+    ])
+    await vi.waitFor(() => expect(view.store.get().status).toBe('idle'))
+    view.dispose()
+    await host.close()
+  })
+
+  it('keeps a rejected approval visible and lets the view retry it', async () => {
+    const { host, session, view } = await openView([
+      () => toolCall('remove', {}, 'view-retry'),
+      () => text('Removed after retry.'),
+    ])
+    await view.send('remove')
+    await vi.waitFor(() => expect(view.store.get().approvals).toHaveLength(1))
+    const id = view.store.get().approvals[0]?.id
+    const receipt = await session.resolve([
+      { interruptId: 'wrong', status: 'resolved', payload: true },
+    ])
+    await expect(session.operation(receipt.operationId ?? '')).rejects.toThrow()
+    await vi.waitFor(() =>
+      expect(view.store.get().approvals.map((item) => item.id)).toEqual([id]),
+    )
+    view.approveAll()
+    await vi.waitFor(() => expect(view.store.get().approvals).toEqual([]))
+    await vi.waitFor(() =>
+      expect(JSON.stringify(view.store.get().messages)).toContain(
+        'Removed after retry.',
+      ),
+    )
+    view.dispose()
+    await host.close()
+  })
+
+  it('reserves approval actions during a running resolve, and does not restore them after the tool ran', async () => {
+    const hold = gate()
+    const { host, session, view, calls } = await openView([
+      () => toolCall('remove', {}, 'slow-approval'),
+      () =>
+        (async function* () {
+          await hold.opened
+          throw new Error('provider failed before commit')
+        })(),
+    ])
+    const errors: Array<string> = []
+    view.on('error', (message) => errors.push(message))
+    await view.send('remove')
+    await vi.waitFor(() => expect(view.store.get().approvals).toHaveLength(1))
+    const resolve = vi.spyOn(session, 'resolve')
+    view.approveAll()
+    await vi.waitFor(() => expect(calls).toHaveLength(2))
+    expect(session.snapshot().pendingInterrupts).toEqual([])
+    expect(view.store.get().approvals).toEqual([])
+    view.approveAll()
+    expect(resolve).toHaveBeenCalledTimes(1)
+    hold.open()
+    await vi.waitFor(() => expect(errors.length).toBeGreaterThan(0))
+    // The approved tool ran before the failure, so the approval is used up.
+    // Offering it again would run the tool a second time.
+    expect(session.snapshot().pendingInterrupts).toEqual([])
+    expect(view.store.get().approvals).toEqual([])
+    view.approveAll()
+    expect(resolve).toHaveBeenCalledTimes(1)
+    view.dispose()
+    await host.close()
+  })
+
+  it('runs commands, shows their text, and follows plugin state and events', async () => {
+    const { host, view } = await openView([])
+    const pinged: Array<number> = []
+    view.on(Pinged, (value) => pinged.push(value.count))
+    expect(view.store.get().plugins).toEqual({ 'test/pinger': { pings: 0 } })
+    expect(view.store.get().commands.map((command) => command.name)).toEqual([
+      'ping',
+    ])
+
+    await view.send('/ping')
+
+    await vi.waitFor(() => expect(pinged).toEqual([1]))
+    expect(view.store.get().plugins).toEqual({ 'test/pinger': { pings: 1 } })
+    expect(view.store.get().messages).toContainEqual(
+      expect.objectContaining({
+        role: 'notice',
+        kind: 'command',
+        text: 'pong',
+      }),
+    )
+    view.dispose()
+    await host.close()
+  })
+
+  it('shows a rejected command as a notice and an error event', async () => {
+    const { host, view } = await openView([])
+    const errors: Array<string> = []
+    view.on('error', (message) => errors.push(message))
+
+    await view.command('nope')
+
+    await vi.waitFor(() =>
+      expect(errors).toEqual(['Not accepted: unknown_command']),
+    )
+    view.dispose()
+    await host.close()
+  })
+
+  it('shows history after a restart, then the notices added before ready', async () => {
+    const persistence = memoryPersistence()
+    const first = await open([() => text('Saved answer.')], persistence)
+    await first.session.prompt('remember this')
+    await first.host.close()
+
+    const second = await open([], persistence)
+    const view = createSessionView(second.session)
+    view.notice('Welcome back.')
+    await view.ready
+
+    expect(view.store.get().messages).toEqual([
+      expect.objectContaining({ role: 'user', text: 'remember this' }),
+      expect.objectContaining({
+        role: 'assistant',
+        parts: [{ type: 'text', text: 'Saved answer.' }],
+      }),
+      expect.objectContaining({
+        role: 'notice',
+        kind: 'ui',
+        text: 'Welcome back.',
+      }),
+    ])
+    view.dispose()
+    await second.host.close()
+  })
+
+  it('stops after dispose', async () => {
+    const { host, session } = await open([])
+    // The host also reads `session.snapshot()` for its status feed. Count
+    // only the reads of the view.
+    const snapshot = vi.fn(() => session.snapshot())
+    const view = createSessionView(
+      new Proxy(session, {
+        get: (target, key) =>
+          key === 'snapshot' ? snapshot : Reflect.get(target, key),
+      }),
+    )
+    await view.ready
+    const before = view.store.get()
+    snapshot.mockClear()
+
+    view.dispose()
+    await session.command('ping')
+    await new Promise((resolve) => setTimeout(resolve, 20))
+
+    expect(view.store.get()).toEqual({ ...before, connection: 'closed' })
+    expect(snapshot).not.toHaveBeenCalled()
+    await expect(view.send('hi')).rejects.toThrow('disposed')
+    expect(() => view.approve('x')).toThrow('disposed')
+    await host.close()
+  })
+
+  it('works the same through createHarnessHandler and createHarnessClient', async () => {
+    const { host, harness } = await open([
+      () => toolCall('remove', {}, 'c1'),
+      () => text('Removed it.'),
+    ])
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      canAccess: () => true,
+      authorize: () => ({ id: 'u' }),
+    })
+    const client = createHarnessClient({
+      url: 'http://local/api/harness',
+      threadId: 't',
+      fetch: (input, init) => handler(new Request(input, init)),
+    })
+    const view = createSessionView(client)
+    await view.ready
+
+    await view.send('remove the file')
+    await vi.waitFor(() => expect(view.store.get().approvals).toHaveLength(1))
+    view.approveAll()
+
+    await vi.waitFor(() =>
+      expect(JSON.stringify(view.store.get().messages)).toContain(
+        'Removed it.',
+      ),
+    )
+    expect(view.store.get().connection).toBe('open')
+    view.dispose()
+    await host.close()
+  })
+
+  it('shows a command or setting that a client may not use, once each', async () => {
+    const harness = defineHarness({
+      name: 'test/view-refused',
+      adapter: mockAdapter([]).adapter,
+      plugins: () => [pinger],
+      // No plugin has `missing`, so the session refuses it with an event.
+      expose: { config: ['missing'] },
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const handler = createHarnessHandler({
+      host,
+      harness,
+      canAccess: () => true,
+      authorize: () => ({ id: 'u' }),
+    })
+    const view = createSessionView(
+      createHarnessClient({
+        url: 'http://local/api/harness',
+        threadId: 't',
+        fetch: (input, init) => handler(new Request(input, init)),
+      }),
+    )
+    await view.ready
+    const errors: Array<string> = []
+    view.on('error', (message) => errors.push(message))
+
+    await view.setConfig({ key: 'missing', value: 1 })
+    await vi.waitFor(() =>
+      expect(errors).toEqual(['Not accepted: unknown_config']),
+    )
+    await view.setConfig({ key: 'mode', value: 'bypass' })
+    await view.command('ping')
+    await view.send('/ping')
+
+    const refused = 'Not accepted: not_exposed'
+    await vi.waitFor(() => expect(errors).toHaveLength(4))
+    expect(errors).toEqual([
+      'Not accepted: unknown_config',
+      refused,
+      refused,
+      refused,
+    ])
+    const notices = view.store
+      .get()
+      .messages.flatMap((message) =>
+        message.role === 'notice' ? [[message.kind, message.text]] : [],
+      )
+    expect(notices).toEqual([
+      ['rejected', 'Not accepted: unknown_config'],
+      ['rejected', refused],
+      ['rejected', refused],
+      ['rejected', refused],
+    ])
+    view.dispose()
+    await host.close()
+  })
+})
+
+describe('the agents of a session view', () => {
+  /** A session with one `writer` run that waits for `hold`. */
+  async function openWriter() {
+    const hold = gate()
+    const writer = defineAgent({
+      name: 'writer',
+      description: 'Writes when the test lets it',
+      run: async () => {
+        await hold.opened
+        return 'Draft.'
+      },
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/view-agents',
+        adapter: mockAdapter([]).adapter,
+        agents: [writer],
+      }),
+      { threadId: 't' },
+    )
+    const run = session.agents.writer.start()
+    return { hold, host, session, run }
+  }
+
+  it('sends a message to a running agent', async () => {
+    const { hold, host, session, run } = await openWriter()
+    const view = createSessionView(session)
+    await view.ready
+
+    const [agent] = view.store.get().agents
+    const receipt = await agent?.send('Add a title.', { mode: 'followUp' })
+
+    expect(agent).toMatchObject({ id: run.id, name: 'writer' })
+    expect(receipt).toMatchObject({ status: 'queued' })
+    expect(session.agentRuns().map((item) => item.status)).toEqual([
+      'running',
+      'queued',
+    ])
+    hold.open()
+    await run
+    view.dispose()
+    await host.close()
+  })
+
+  it('rejects send when the view source cannot send to agents', async () => {
+    const { hold, host, session, run } = await openWriter()
+    const source: SessionViewSource = {
+      prompt: (message) => session.prompt(message),
+      steer: (message) => session.steer(message),
+      resolve: (resume) => session.resolve(resume),
+      cancel: (operationId) => session.cancel(operationId),
+      answer: ({ questionId, value }) => session.answer({ questionId, value }),
+      command: (name, input) => session.command(name, input),
+      setConfig: ({ key, value }) => session.setConfig({ key, value }),
+      events: (options) => session.events(options),
+      snapshot: () => session.snapshot(),
+      transcript: () => session.transcript(),
+      describe: () => session.describe(),
+    }
+    const view = createSessionView(source)
+    await view.ready
+
+    const [agent] = view.store.get().agents
+
+    await expect(agent?.send('x')).rejects.toThrow(
+      'This view source cannot send messages to agents.',
+    )
+    hold.open()
+    await run
+    view.dispose()
+    await host.close()
+  })
+
+  it('shows what a child agent wrote after a reload', async () => {
+    const writer = defineAgent({
+      name: 'writer',
+      description: 'Writes notes',
+      run: (ctx) =>
+        ctx.chat({ adapter: mockAdapter(() => text('Note 1')).adapter }),
+    })
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    const session = await host.open(
+      defineHarness({
+        name: 'test/view-children',
+        adapter: mockAdapter([
+          () => toolCall('writer', { prompt: 'Take notes' }, 'call-1'),
+          () => text('Done.'),
+        ]).adapter,
+        subagents: { agents: [writer] },
+      }),
+      { threadId: 't' },
+    )
+    await session.prompt('Notes, please')
+
+    const view = createSessionView(session)
+    await view.ready
+
+    await vi.waitFor(() =>
+      expect(view.store.get().messages[1]).toMatchObject({
+        role: 'assistant',
+        parts: [
+          { type: 'tool-call', id: 'call-1', status: 'done' },
+          {
+            type: 'agent',
+            name: 'writer',
+            status: 'done',
+            parts: [{ type: 'text', text: 'Note 1' }],
+          },
+        ],
+      }),
+    )
+    view.dispose()
+    await host.close()
+  })
+})
diff --git a/packages/ai-harness/vite.config.ts b/packages/ai-harness/vite.config.ts
index 1f3542380f..602e82750f 100644
--- a/packages/ai-harness/vite.config.ts
+++ b/packages/ai-harness/vite.config.ts
@@ -28,7 +28,7 @@ const config = defineConfig({
 export default mergeConfig(
   config,
   tanstackViteConfig({
-    entry: ['./src/index.ts'],
+    entry: ['./src/index.ts', './src/client.ts', './src/view/index.ts'],
     srcDir: './src',
     cjs: false,
   }),
diff --git a/packages/ai-mcp/package.json b/packages/ai-mcp/package.json
index ad7268685a..c2df5435c9 100644
--- a/packages/ai-mcp/package.json
+++ b/packages/ai-mcp/package.json
@@ -52,6 +52,14 @@
     "./server/stdio": {
       "types": "./dist/esm/server/stdio.d.ts",
       "import": "./dist/esm/server/stdio.js"
+    },
+    "./connector": {
+      "types": "./dist/esm/connector.d.ts",
+      "import": "./dist/esm/connector.js"
+    },
+    "./harness": {
+      "types": "./dist/esm/harness.d.ts",
+      "import": "./dist/esm/harness.js"
     }
   },
   "files": [
@@ -76,7 +84,17 @@
     "@tanstack/ai": "workspace:^",
     "jose": "^6.2.12"
   },
+  "peerDependencies": {
+    "@tanstack/ai-harness": "workspace:^"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/ai-harness": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@tanstack/ai-harness": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
     "@vitest/coverage-v8": "4.1.10",
     "jiti": "^2.4.2",
     "json-schema-to-typescript": "^15.0.4",
diff --git a/packages/ai-mcp/skills/ai-mcp/SKILL.md b/packages/ai-mcp/skills/ai-mcp/SKILL.md
index d5b580c6b4..397bc4f7d6 100644
--- a/packages/ai-mcp/skills/ai-mcp/SKILL.md
+++ b/packages/ai-mcp/skills/ai-mcp/SKILL.md
@@ -17,6 +17,7 @@ sources:
   - 'TanStack/ai:packages/ai-mcp/src/transport.ts'
   - 'TanStack/ai:packages/ai-mcp/src/server/create-server.ts'
   - 'TanStack/ai:packages/ai-mcp/src/server/stdio.ts'
+  - 'TanStack/ai:packages/ai-mcp/src/harness-plugin.ts'
 ---
 
 # `@tanstack/ai-mcp`
@@ -54,6 +55,12 @@ The package has these subpaths:
 - `./server` exports `createMCPServer`.
 - `./server/stdio` exports `serveMCPStdio`.
 - `./apps` exports `createMcpAppCallHandler`.
+- `./harness` exports `createHarnessMcpServer` and the `mcp()` harness
+  plugin. `createHarnessMcpServer` serves a TanStack AI harness as an MCP
+  server. See `docs/harness/mcp-server.md`, and "`mcp()`: MCP servers in a
+  harness" below.
+- `./connector` exports `mcpConnector`: one OAuth MCP server as a harness
+  plugin. See `docs/harness/mcp.md`.
 
 Import `./stdio` and `./server/stdio` only from Node code.
 Those entries use Node I/O.
@@ -818,6 +825,65 @@ await using pool = await createMCPClients({
 })
 ```
 
+## `mcp()`: MCP servers in a harness
+
+In a TanStack AI harness, use the `mcp()` plugin. It connects each server,
+gives the model the tools as `<server>_<tool>`, and adds a `/mcp` command
+that shows the status of each server.
+
+```typescript
+import { defineHarness } from '@tanstack/ai-harness'
+import { openaiText } from '@tanstack/ai-openai'
+import { mcp } from '@tanstack/ai-mcp/harness'
+
+const agent = defineHarness({
+  name: 'acme/agent',
+  adapter: openaiText('gpt-6.1-sol'),
+  plugins: () => [
+    mcp({
+      servers: {
+        files: {
+          type: 'stdio',
+          command: 'npx',
+          args: ['-y', '@modelcontextprotocol/server-filesystem', '.'],
+        },
+        docs: {
+          type: 'http',
+          url: 'https://mcp.example.com/mcp',
+          headers: { authorization: `Bearer ${process.env.DOCS_TOKEN}` },
+          timeoutMs: 10_000,
+        },
+        notion: {
+          type: 'http',
+          url: 'https://mcp.notion.com/mcp',
+          oauth: true,
+        },
+      },
+    }),
+  ],
+})
+```
+
+How it works:
+
+- Each server connects on its own, in the background. The first turn waits
+  for the connections.
+- A server that fails gets the status `failed` with its error. The tools of
+  the other servers still work.
+- The status of a server is `connecting`, `connected`, or `failed`. `/mcp`
+  prints it. A UI reads `snapshot().plugins['tanstack/mcp'].servers`.
+- A `stdio` server runs as a child process (Node only). It stops when the
+  session closes.
+- A server request for input (MCP elicitation, spec 2025 and 2026) becomes
+  a session question. The tool call waits for `session.answer()`.
+
+Options for each server:
+
+- `timeoutMs`: the limit for the connect, the tool list, and each tool call
+  of that server.
+- `oauth: true` (`http` only): sign in like `mcpConnector`. The user runs
+  `/connect <name>`, and the tools come after the sign-in.
+
 ## Abort signal — cancelling in-flight MCP calls
 
 TanStack AI stops waiting for MCP tool calls when the chat run's
diff --git a/packages/ai-mcp/src/client.ts b/packages/ai-mcp/src/client.ts
index 64726c9c3b..1ad773326c 100644
--- a/packages/ai-mcp/src/client.ts
+++ b/packages/ai-mcp/src/client.ts
@@ -37,6 +37,8 @@ import type {
 } from './types'
 import type {
   ClientOptions,
+  ElicitRequest,
+  ElicitResult,
   GetPromptResult,
   McpSubscription,
   Prompt,
@@ -190,6 +192,7 @@ class MCPClientImpl<
     transport?: TransportConfig,
     clientOptions?: ClientOptions,
     policy: ToolPolicy = {},
+    onElicit?: OnElicit,
   ) {
     this.prefix = prefix
     this.#transport = transport
@@ -216,6 +219,12 @@ class MCPClientImpl<
         },
       },
     )
+    // A spec 2025 server asks for input with a request to the client.
+    if (onElicit) {
+      this.#client.setRequestHandler('elicitation/create', (request) =>
+        onElicit(request.params),
+      )
+    }
   }
 
   getInfo(): {
@@ -591,9 +600,18 @@ export async function createMCPClient(
   return connectTransport(options)
 }
 
-async function connectTransport<
+/** Answers a spec 2025 `elicitation/create` request. */
+export type OnElicit = (
+  params: ElicitRequest['params'],
+) => Promise<ElicitResult>
+
+/**
+ * Connects a client to a transport. The harness passes `onElicit` to answer
+ * the `elicitation/create` requests of spec 2025 servers.
+ */
+export async function connectTransport<
   TServer extends ServerDescriptor = AutomaticDescriptor,
->(options: MCPClientOptions) {
+>(options: MCPClientOptions, onElicit?: OnElicit) {
   const transport = await resolveTransport(options.transport)
   const impl = new MCPClientImpl<TServer>(
     options.prefix,
@@ -609,6 +627,7 @@ async function connectTransport<
       toolName: options.toolName,
       requestOptions: options.requestOptions,
     },
+    onElicit,
   )
   await impl.connect(transport)
   return impl
diff --git a/packages/ai-mcp/src/connector.ts b/packages/ai-mcp/src/connector.ts
new file mode 100644
index 0000000000..879e6a49a9
--- /dev/null
+++ b/packages/ai-mcp/src/connector.ts
@@ -0,0 +1,384 @@
+import { randomBytes } from 'node:crypto'
+import { auth } from '@modelcontextprotocol/client'
+import {
+  AuthRequiredError,
+  defineCommand,
+  definePlugin,
+  startLoopbackReceiver,
+} from '@tanstack/ai-harness'
+import { connectTransport } from './client'
+import { MCPConnectionError } from './errors'
+import { askForInput, elicitFor, harnessClientOptions } from './harness-plugin'
+import type {
+  OAuthClientProvider,
+  OAuthDiscoveryState,
+  StoredOAuthClientInformation,
+} from '@modelcontextprotocol/client'
+import type { AnyTool } from '@tanstack/ai'
+import type { CredentialsAccess, Principal } from '@tanstack/ai-harness'
+import type { MCPClient } from './client'
+import type { MCPClientOptions } from './types'
+
+export interface McpConnectorOptions {
+  /** A short id, for example `'notion'`. Commands are `connect:<id>` and `disconnect:<id>`. */
+  id: string
+  label: string
+  /** The MCP server URL (Streamable HTTP), for example `https://mcp.notion.com/mcp`. */
+  url: string
+  /** Tool name prefix. Default: the id. Tools are named `<prefix>_<tool>` unless `toolName` is set. */
+  prefix?: string
+  /**
+   * The name the model sees for each tool. Wins over `prefix`.
+   * See `MCPClientOptions.toolName`.
+   */
+  toolName?: MCPClientOptions['toolName']
+  /** Sent with the connect handshake, tool lists, tool calls, resources, and prompts. See `MCPClientOptions.requestOptions`. */
+  requestOptions?: MCPClientOptions['requestOptions']
+  /** OAuth scopes to ask for. Default: what the server offers. */
+  scopes?: ReadonlyArray<string>
+  /** The client name shown on the consent screen. Default `'TanStack AI Harness'`. */
+  clientName?: string
+  /**
+   * Ask for approval before tools that can change data. Default: every tool
+   * the server does not mark `readOnlyHint`.
+   */
+  needsApproval?: (tool: {
+    name: string
+    annotations?: { readOnlyHint?: boolean }
+  }) => boolean
+  /** Test hook for the OAuth and MCP requests. */
+  fetch?: typeof fetch
+}
+
+/**
+ * An `OAuthClientProvider` for the MCP SDK that keeps tokens (and the client
+ * that dynamic registration made) in the harness credential store.
+ */
+function credentialProvider(
+  id: string,
+  credentials: CredentialsAccess,
+  options: {
+    redirectUri: string
+    clientName: string
+    scopes: ReadonlyArray<string> | undefined
+    state?: string
+    onRedirect?: (url: URL) => void
+  },
+) {
+  const { state } = options
+  let client: StoredOAuthClientInformation | undefined
+  let verifier = ''
+  let discovery: OAuthDiscoveryState | undefined
+  const stored = async () => {
+    const credential = await credentials.get(id)
+    return credential?.type === 'oauth' ? credential : undefined
+  }
+  return {
+    get redirectUrl() {
+      return options.redirectUri
+    },
+    get clientMetadata() {
+      return {
+        client_name: options.clientName,
+        redirect_uris: [options.redirectUri],
+        grant_types: ['authorization_code', 'refresh_token'],
+        response_types: ['code'],
+        token_endpoint_auth_method: 'none',
+        ...(options.scopes?.length ? { scope: options.scopes.join(' ') } : {}),
+      }
+    },
+    ...(state ? { state: () => state } : {}),
+    clientInformation: async () => {
+      if (client) return client
+      // A new sign-in registers a client for its own loopback port.
+      if (options.onRedirect) return undefined
+      const saved = (await stored())?.client
+      if (!saved) return undefined
+      // Kept, so the tokens saved after a refresh keep this client.
+      client = {
+        client_id: saved.clientId,
+        ...(saved.clientSecret ? { client_secret: saved.clientSecret } : {}),
+        ...(saved.issuer ? { issuer: saved.issuer } : {}),
+      }
+      return client
+    },
+    saveClientInformation: (information) => {
+      client = information
+    },
+    tokens: async () => {
+      if (options.onRedirect) return undefined
+      const credential = await stored()
+      if (!credential) return undefined
+      return {
+        access_token: credential.accessToken,
+        token_type: 'Bearer',
+        ...(credential.refreshToken
+          ? { refresh_token: credential.refreshToken }
+          : {}),
+        ...(credential.expiresAt
+          ? {
+              expires_in: Math.max(
+                0,
+                Math.floor((credential.expiresAt - Date.now()) / 1000),
+              ),
+            }
+          : {}),
+        // The SDK checks that the tokens come from the same server (SEP-2352).
+        ...(credential.client?.issuer
+          ? { issuer: credential.client.issuer }
+          : {}),
+      }
+    },
+    saveTokens: async (tokens) => {
+      const information = client
+      // `auth()` reads or registers the client before it saves tokens.
+      if (!information) {
+        throw new Error('The MCP SDK saved OAuth tokens before the client.')
+      }
+      // A new sign-in replaces the old one, with all its tokens. On a
+      // refresh, the SDK passes the old refresh token itself.
+      await credentials.set({
+        id,
+        credential: {
+          type: 'oauth',
+          accessToken: tokens.access_token,
+          ...(tokens.refresh_token
+            ? { refreshToken: tokens.refresh_token }
+            : {}),
+          ...(tokens.expires_in
+            ? { expiresAt: Date.now() + tokens.expires_in * 1000 }
+            : {}),
+          ...(tokens.scope ? { scopes: tokens.scope.split(' ') } : {}),
+          client: {
+            clientId: information.client_id,
+            ...(information.client_secret
+              ? { clientSecret: information.client_secret }
+              : {}),
+            redirectUri: options.redirectUri,
+            issuer: information.issuer,
+          },
+        },
+      })
+    },
+    // The SDK calls this with 'client' or 'tokens' when the server refuses
+    // the saved client or refresh token, for example a revoked refresh token.
+    // Both are in one saved credential, so either scope deletes it, and the
+    // user signs in again. A new sign-in keeps the old one until it works.
+    invalidateCredentials: async () => {
+      if (!options.onRedirect) await credentials.delete(id)
+    },
+    redirectToAuthorization: (url) => {
+      // Outside `/connect`, a missing or revoked sign-in stops the tool.
+      if (!options.onRedirect) throw new AuthRequiredError(id)
+      options.onRedirect(url)
+    },
+    saveCodeVerifier: (value) => {
+      verifier = value
+    },
+    codeVerifier: () => verifier,
+    // Kept like the code verifier: `/connect` checks that the code comes
+    // from the authorization server it found first (SEP-2352).
+    saveDiscoveryState: (value) => {
+      discovery = value
+    },
+    discoveryState: () => discovery,
+  } satisfies OAuthClientProvider
+}
+
+/** The MCP sign-in of one sender, with its client and tools once found. */
+interface Connection {
+  connected: boolean
+  client?: MCPClient
+  tools?: ReadonlyArray<AnyTool>
+}
+
+/**
+ * A plugin that signs the user in to a remote MCP server (for example Notion
+ * or Linear) and gives the model its tools, the way Claude Code connects to
+ * MCP servers:
+ *
+ * - `/connect <id>` finds the server's OAuth settings, registers a client,
+ *   and opens the browser (PKCE, loopback on `127.0.0.1`).
+ * - The tokens stay in the credential store. The model never sees them.
+ * - After sign-in, the next turn has the server's tools, named
+ *   `<prefix>_<tool>` by default. `toolName` can change the names.
+ *   Tools that can change data ask for approval.
+ *
+ * @example
+ * ```ts
+ * const notion = mcpConnector({ id: 'notion', label: 'Notion', url: 'https://mcp.notion.com/mcp' })
+ * ```
+ */
+export function mcpConnector(options: McpConnectorOptions) {
+  const { id, label, url } = options
+  const prefix = options.prefix ?? id
+  const clientName = options.clientName ?? 'TanStack AI Harness'
+  return definePlugin({
+    name: `connector/${id}`,
+    setup: async (ctx) => {
+      // One sign-in per sender: in a shared thread, one person's sign-in,
+      // client, and tools never serve another person's turn.
+      const connections = new Map<string, Connection>()
+      const keyOf = (principal: Principal | undefined) =>
+        principal
+          ? JSON.stringify([principal.tenantId ?? null, principal.id])
+          : ''
+      const close = async (connection: Connection | undefined) => {
+        await connection?.client?.close().catch(() => {})
+      }
+      /** Set the sign-in of `principal`, and drop its old client and tools. */
+      const signedIn = async (
+        principal: Principal | undefined,
+        connected: boolean,
+      ) => {
+        const key = keyOf(principal)
+        const old = connections.get(key)
+        connections.set(key, { connected })
+        await close(old)
+      }
+      await ctx.resources.acquire(
+        () => undefined,
+        () => Promise.all([...connections.values()].map(close)),
+      )
+
+      return {
+        prompts: [
+          {
+            id: `connector/${id}:status`,
+            // Read after `discoverTools`, which finds the sender's state.
+            text: () =>
+              connections.get(keyOf(ctx.session.principal))?.connected
+                ? ''
+                : `${label} is not connected. If the user asks for ${label}, tell them to run /connect ${id}.`,
+          },
+        ],
+        // Runs in a turn, so `ctx.session.principal` and `ctx.credentials`
+        // are the turn's sender.
+        discoverTools: async () => {
+          const key = keyOf(ctx.session.principal)
+          let connection = connections.get(key)
+          if (!connection) {
+            connection = { connected: (await ctx.credentials.get(id)) !== null }
+            connections.set(key, connection)
+          }
+          if (!connection.connected) return []
+          if (!connection.tools) {
+            // The SDK only refreshes tokens for a client with a redirect URL.
+            // Without one it treats the client as machine-to-machine. A new
+            // browser sign-in still happens only through /connect.
+            const saved = await ctx.credentials.get(id)
+            const redirectUri =
+              (saved?.type === 'oauth'
+                ? saved.client?.redirectUri
+                : undefined) ?? 'http://127.0.0.1/callback'
+            try {
+              connection.client = await connectTransport(
+                {
+                  transport: {
+                    type: 'http',
+                    url,
+                    authProvider: credentialProvider(id, ctx.credentials, {
+                      redirectUri,
+                      clientName,
+                      scopes: options.scopes,
+                    }),
+                    ...(options.fetch ? { fetch: options.fetch } : {}),
+                  },
+                  prefix,
+                  toolName: options.toolName,
+                  requestOptions: options.requestOptions,
+                  needsApproval:
+                    options.needsApproval ??
+                    ((tool) => tool.annotations?.readOnlyHint !== true),
+                  clientOptions: harnessClientOptions,
+                },
+                elicitFor(ctx.session),
+              )
+            } catch (error) {
+              // The server wants a new sign-in: ask the user to run /connect.
+              // Other failures, for example a server that is down, stay
+              // connection errors.
+              const needsSignIn =
+                error instanceof MCPConnectionError &&
+                error.cause instanceof AuthRequiredError
+              if (!needsSignIn) throw error
+              connection.connected = false
+              ctx.session.authRequired({ connector: id })
+              throw error.cause
+            }
+            const client = connection.client
+            // A failed tool list closes the client: the next turn connects
+            // again, and must not leave this one open.
+            const listed = await client
+              .tools()
+              .catch(async (error: unknown) => {
+                connection.client = undefined
+                await client.close().catch(() => {})
+                throw error
+              })
+            connection.tools = askForInput(
+              listed as ReadonlyArray<AnyTool>,
+              ctx.session,
+            )
+          }
+          return connection.tools
+        },
+        commands: {
+          [`connect:${id}`]: defineCommand({
+            description: `Sign in to ${label}`,
+            // The sign-in belongs to the user who runs the command.
+            run: async (_input, { credentials, principal }) => {
+              const receiver = await startLoopbackReceiver()
+              const state = randomBytes(16).toString('base64url')
+              try {
+                const provider = credentialProvider(id, credentials, {
+                  redirectUri: receiver.redirectUri,
+                  clientName,
+                  scopes: options.scopes,
+                  state,
+                  onRedirect: (authorizationUrl) =>
+                    ctx.session.authRequired({
+                      connector: id,
+                      url: authorizationUrl.href,
+                    }),
+                })
+                const fetchFn = options.fetch ? { fetchFn: options.fetch } : {}
+                // A new sign-in has no tokens, so this always ends in a
+                // redirect to the browser.
+                await auth(provider, { serverUrl: url, ...fetchFn })
+                // The error names the service: a sign-in can end minutes later.
+                const { code, iss } = await receiver
+                  .waitForCode(state)
+                  .catch((error: unknown) => {
+                    throw new Error(
+                      `${label}: ${error instanceof Error ? error.message : String(error)}`,
+                    )
+                  })
+                // A server that sends `iss` (RFC 9207), such as Linear, gets
+                // it checked. Without it, the SDK refuses the code.
+                await auth(provider, {
+                  serverUrl: url,
+                  authorizationCode: code,
+                  ...(iss ? { iss } : {}),
+                  ...fetchFn,
+                })
+              } finally {
+                receiver.close()
+              }
+              await signedIn(principal, true)
+              return `Connected to ${label}.`
+            },
+          }),
+          [`disconnect:${id}`]: defineCommand({
+            description: `Sign out of ${label}`,
+            run: async (_input, { credentials, principal }) => {
+              await credentials.delete(id)
+              await signedIn(principal, false)
+              return `Disconnected from ${label}.`
+            },
+          }),
+        },
+      }
+    },
+  })
+}
diff --git a/packages/ai-mcp/src/harness-plugin.ts b/packages/ai-mcp/src/harness-plugin.ts
new file mode 100644
index 0000000000..545300c145
--- /dev/null
+++ b/packages/ai-mcp/src/harness-plugin.ts
@@ -0,0 +1,349 @@
+import { defineCommand, definePlugin } from '@tanstack/ai-harness'
+import { connectTransport } from './client'
+import type { ElicitResult } from '@modelcontextprotocol/client'
+import type { AnyTool, JSONSchema } from '@tanstack/ai'
+import type {
+  AnyCommand,
+  PluginPrompt,
+  PluginSessionApi,
+} from '@tanstack/ai-harness'
+import type { OnElicit } from './client'
+import type { AskInput } from './tools'
+import type { HttpTransportConfig, StdioTransportConfig } from './transport'
+
+/** One server of {@link mcp}, keyed by its name. */
+export type McpServerConfig = (
+  | StdioTransportConfig
+  | (HttpTransportConfig & {
+      /**
+       * Sign in with OAuth, like `mcpConnector`. This adds `/connect <name>`
+       * and `/disconnect <name>`. The tools of the server come after the
+       * sign-in, and the tools that are not read-only ask for approval.
+       * `headers` and `authProvider` do not apply then.
+       */
+      oauth?: boolean
+    })
+) & {
+  /**
+   * The time in milliseconds that this server can take to connect, to send
+   * its tool list, or to answer a tool call. Default: the MCP SDK default,
+   * 60,000.
+   */
+  timeoutMs?: number
+  /**
+   * Give the tools of this server to code mode: the `codeMode()` plugin of
+   * `@tanstack/ai-code-mode` takes them out of the tool list and lets the
+   * model call them from `execute_typescript`. Without that plugin, nothing
+   * changes.
+   */
+  codeMode?: boolean
+}
+
+/**
+ * The status of one server. UIs read the list from
+ * `snapshot().plugins['tanstack/mcp'].servers`.
+ */
+export type McpServerStatus = {
+  name: string
+  /** How many tools the server gives the model. */
+  toolCount: number
+} & (
+  | { status: 'connecting' | 'connected' }
+  | { status: 'failed'; error: string }
+)
+
+/**
+ * A harness plugin that connects MCP servers and gives the model their
+ * tools, named `<server>_<tool>`.
+ *
+ * - Each server connects on its own. A server that fails does not stop the
+ *   others: it gets the status `failed` with the error.
+ * - The servers connect in the background. The first turn waits for them.
+ * - `/mcp` lists the servers and their status. UIs read the same list from
+ *   the plugin state.
+ * - A `stdio` server runs as a child process (Node only). It stops when the
+ *   session closes.
+ * - An `http` server with `oauth: true` signs in through `/connect <name>`.
+ *
+ * @param options.servers - The servers, keyed by name. The name is the tool
+ *   prefix.
+ *
+ * @example
+ * ```ts
+ * import { mcp } from '@tanstack/ai-mcp/harness'
+ *
+ * plugins: () => [
+ *   mcp({
+ *     servers: {
+ *       files: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] },
+ *       docs: { type: 'http', url: 'https://mcp.example.com/mcp', timeoutMs: 10_000 },
+ *       notion: { type: 'http', url: 'https://mcp.notion.com/mcp', oauth: true },
+ *     },
+ *   }),
+ * ]
+ * ```
+ */
+export function mcp(options: {
+  servers: Readonly<Record<string, McpServerConfig>>
+}) {
+  const servers = Object.entries(options.servers)
+  return definePlugin({
+    name: 'tanstack/mcp',
+    setup: async (ctx) => {
+      const statuses = new Map<string, McpServerStatus>()
+      for (const [name] of servers) {
+        statuses.set(name, { name, status: 'connecting', toolCount: 0 })
+      }
+      const state = ctx.state({ servers: [...statuses.values()] })
+      const setStatus = async (status: McpServerStatus) => {
+        const old = JSON.stringify(statuses.get(status.name))
+        statuses.set(status.name, status)
+        if (old === JSON.stringify(status)) return
+        await state.update(() => ({ servers: [...statuses.values()] }))
+      }
+      // State from an earlier run of this session is out of date.
+      await state.update(() => ({ servers: [...statuses.values()] }))
+
+      /** Connects one server, in the background. Never rejects. */
+      const connect = async (name: string, server: McpServerConfig) => {
+        const opened = await ctx.resources
+          .acquire(
+            async () => {
+              // Loaded here: the stdio transport needs node:child_process.
+              const transport =
+                server.type === 'stdio'
+                  ? (await import('./stdio')).stdioTransport(server)
+                  : server
+              const client = await connectTransport(
+                {
+                  transport,
+                  prefix: name,
+                  requestOptions: requestOptionsOf(server),
+                  clientOptions: harnessClientOptions,
+                },
+                elicitFor(ctx.session),
+              )
+              try {
+                const tools = askForInput(
+                  forCodeMode(server, await client.tools()),
+                  ctx.session,
+                )
+                return { client, tools }
+              } catch (error) {
+                // Connected, but no tool list: the server failed.
+                await client.close().catch(() => undefined)
+                throw error
+              }
+            },
+            ({ client }) => client.close(),
+          )
+          .catch((error: unknown) => new Error(errorText(error)))
+        const failed = opened instanceof Error
+        const status: McpServerStatus = failed
+          ? { name, status: 'failed', error: opened.message, toolCount: 0 }
+          : { name, status: 'connected', toolCount: opened.tools.length }
+        // After the session closed, the state store can be gone. `/mcp`
+        // reads `statuses`, which is set first.
+        await setStatus(status).catch(() => undefined)
+        return failed ? [] : opened.tools
+      }
+
+      const commands: Record<string, AnyCommand> = {
+        mcp: defineCommand({
+          description: 'Show the MCP servers and their status',
+          run: () => [...statuses.values()].map(statusLine).join('\n'),
+        }),
+      }
+      const prompts: Array<PluginPrompt> = []
+      // One tool list for each server, in the order of `servers`.
+      const lists = await Promise.all(
+        servers.map(async (entry) => {
+          const [name, server] = entry
+          const isOAuth = server.type === 'http' && server.oauth === true
+          if (!isOAuth) {
+            const connecting = connect(name, server)
+            return () => connecting
+          }
+          // Loaded here: the connector needs node:crypto and node:http.
+          const { mcpConnector } = await import('./connector')
+          const connector = await mcpConnector({
+            id: name,
+            label: name,
+            url: server.url,
+            requestOptions: requestOptionsOf(server),
+            ...(server.fetch ? { fetch: server.fetch } : {}),
+          }).setup(ctx)
+          Object.assign(commands, connector.commands)
+          prompts.push(...connector.prompts)
+          // The sign-in belongs to the sender of the turn, so the status is
+          // the one of the last turn.
+          return async () => {
+            try {
+              const tools = await connector.discoverTools()
+              const signedIn =
+                tools.length > 0 || (await ctx.credentials.get(name)) !== null
+              await setStatus(
+                signedIn
+                  ? { name, status: 'connected', toolCount: tools.length }
+                  : {
+                      name,
+                      status: 'failed',
+                      error: `Not signed in. Run /connect ${name}.`,
+                      toolCount: 0,
+                    },
+              )
+              return forCodeMode(server, tools)
+            } catch (error) {
+              // One server that fails must not hide the tools of the others.
+              await setStatus({
+                name,
+                status: 'failed',
+                error: errorText(error),
+                toolCount: 0,
+              })
+              return []
+            }
+          }
+        }),
+      )
+
+      return {
+        commands,
+        prompts,
+        discoverTools: async () => {
+          const found = await Promise.all(lists.map((list) => list()))
+          return found.flat()
+        },
+      }
+    },
+  })
+}
+
+/**
+ * The harness asks the user for form and URL elicitations, so its clients
+ * declare both. `chat()` clients keep the default: form only.
+ */
+export const harnessClientOptions = {
+  capabilities: { elicitation: { form: {}, url: {} } },
+}
+
+/**
+ * Ask the session user when an MCP tool asks for input (a form or a URL
+ * elicitation). The tool call waits for the answer, then sends it to the
+ * server. On spec 2026, a tool call can ask up to 5 times. The answer is the
+ * form content, or an MCP result such as `{ action: 'decline' }` or
+ * `{ action: 'cancel' }`.
+ */
+export function askForInput(
+  tools: ReadonlyArray<AnyTool>,
+  session: PluginSessionApi,
+) {
+  const askInput: AskInput = async (request) => ({
+    status: 'resolved',
+    payload: await ask(session, request),
+  })
+  return tools.map((tool): AnyTool => {
+    const execute = tool.execute
+    if (!execute) return tool
+    return {
+      ...tool,
+      execute: (args, context) =>
+        execute(args, { ...(isRecord(context) ? context : {}), askInput }),
+    }
+  })
+}
+
+/** Answers the `elicitation/create` requests of a spec 2025 server. */
+export function elicitFor(session: PluginSessionApi): OnElicit {
+  return async (params) => elicitResult(await ask(session, params))
+}
+
+/** Asks the session user for one MCP elicitation request body. */
+async function ask(session: PluginSessionApi, request: unknown) {
+  const body = isRecord(request) ? request : {}
+  const url =
+    body.mode === 'url' && typeof body.url === 'string' ? body.url : undefined
+  const answer = await session.ask({
+    message:
+      typeof body.message === 'string'
+        ? body.message
+        : 'The MCP server asks for input.',
+    schema: isJsonSchema(body.requestedSchema)
+      ? body.requestedSchema
+      : undefined,
+    ...(url ? { url } : {}),
+  })
+  // A URL request has no content: the answer only says "done".
+  return url !== undefined && !(isRecord(answer) && 'action' in answer)
+    ? { action: 'accept' }
+    : answer
+}
+
+/** Maps an answer to the MCP result: decline, cancel, or accept. */
+function elicitResult(answer: unknown): ElicitResult {
+  if (
+    isRecord(answer) &&
+    (answer.action === 'decline' || answer.action === 'cancel')
+  ) {
+    return { action: answer.action }
+  }
+  const content =
+    isRecord(answer) && answer.action === 'accept' ? answer.content : answer
+  return isElicitContent(content)
+    ? { action: 'accept', content }
+    : { action: 'accept' }
+}
+
+// ponytail: the SDK checks the result against the schema of the request.
+function isElicitContent(
+  value: unknown,
+): value is NonNullable<ElicitResult['content']> {
+  return isRecord(value)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+// ponytail: the server owns the schema. The session passes it on as is.
+function isJsonSchema(value: unknown): value is JSONSchema {
+  return isRecord(value)
+}
+
+/** The SDK request options for `timeoutMs`. */
+function requestOptionsOf(server: McpServerConfig) {
+  return server.timeoutMs === undefined
+    ? undefined
+    : { timeout: server.timeoutMs }
+}
+
+/** Marks the tools of a `codeMode: true` server for the `codeMode()` plugin. */
+function forCodeMode(server: McpServerConfig, tools: ReadonlyArray<AnyTool>) {
+  if (server.codeMode !== true) return tools
+  return tools.map((tool) => ({
+    ...tool,
+    metadata: { ...tool.metadata, codeMode: true },
+  }))
+}
+
+function statusLine(server: McpServerStatus) {
+  switch (server.status) {
+    case 'connecting':
+      return `${server.name}: connecting`
+    case 'connected': {
+      const unit = server.toolCount === 1 ? 'tool' : 'tools'
+      return `${server.name}: connected (${server.toolCount} ${unit})`
+    }
+    case 'failed':
+      return `${server.name}: failed: ${server.error}`
+  }
+}
+
+/** The error text for the status. A connect error keeps its reason in `cause`. */
+function errorText(error: unknown) {
+  if (!(error instanceof Error)) return String(error)
+  const { cause } = error
+  return cause instanceof Error
+    ? `${error.message}: ${cause.message}`
+    : error.message
+}
diff --git a/packages/ai-mcp/src/harness.ts b/packages/ai-mcp/src/harness.ts
new file mode 100644
index 0000000000..aaa149a84c
--- /dev/null
+++ b/packages/ai-mcp/src/harness.ts
@@ -0,0 +1,973 @@
+import {
+  EventType,
+  convertSchemaToJsonSchema,
+  readUnopenedInterruptBinding,
+  toolDefinition,
+} from '@tanstack/ai'
+import {
+  HARNESS_EVENTS,
+  isMediaRecord,
+  kindOf,
+  mediaPart,
+  mimeTypeOf,
+} from '@tanstack/ai-harness'
+// The inferred return type names `MCPHandleOptions`. Without an import of
+// `./server/index`, the .d.ts emit writes `./server.js`, which does not resolve.
+import { createMCPServer, resourceDefinition } from './server/index'
+import { toCallToolResult } from './server/tasks'
+import type { ContentPart, Interrupt, JSONSchema } from '@tanstack/ai'
+import type {
+  AnyHarness,
+  Cursor,
+  HarnessHost,
+  HarnessSession,
+  MediaRecord,
+  Operation,
+} from '@tanstack/ai-harness'
+import type { ContentBlock } from '@modelcontextprotocol/server'
+import type { MCPToolContext } from './server/context'
+
+export { mcp } from './harness-plugin'
+export type { McpServerConfig, McpServerStatus } from './harness-plugin'
+
+/** Options for {@link createHarnessMcpServer}. */
+export interface HarnessMcpServerOptions {
+  /** The host that runs the sessions, from `createHarnessHost`. */
+  host: HarnessHost
+  /** The harness to serve. */
+  harness: AnyHarness
+  /** The conversation of a tool call that names no `threadId`. Default `'main'`. */
+  threadId?: string
+  /**
+   * What happens when a turn stops for a tool call that needs approval.
+   * - `'ask'` (default): ask the user in the MCP client (elicitation). A
+   *   client without elicitation gets the approvals in the result. It answers
+   *   them with `approve`, `reject`, or `resolve`.
+   * - `'auto'`: approve every tool call.
+   *
+   * Both modes answer tool approvals only. When the turn also waits for
+   * another kind of interrupt, every interrupt comes back in the result. The
+   * client answers them all with one `resolve`.
+   */
+  approvals?: 'ask' | 'auto'
+  /**
+   * The folders that a `path` attachment of `chat` can read from. A path must
+   * resolve, after every symlink, to a file inside one of them. Leave it out,
+   * and every `path` attachment is refused.
+   *
+   * The stdio CLI (`--mcp`) passes the working folder. An HTTP server should
+   * pass none, because a remote client must not read files on the server.
+   */
+  filePaths?: ReadonlyArray<string>
+  /** The MCP server name. Default: the harness name. */
+  name?: string
+  /** The MCP server version. Default `'1.0.0'`. */
+  version?: string
+}
+
+/** One decision of a `resolve` call, from the client. */
+type Decision = { interruptId: string; approved?: boolean; payload?: unknown }
+
+/** The answer to one interrupt, for `session.resolve`. */
+type Answer = { interruptId: string; payload: unknown }
+
+/** One file of a `chat` call, from the client. */
+type Attachment =
+  | { path: string; name?: string }
+  | { url: string; mimeType?: string; name?: string }
+  | { data: string; mimeType: string; name?: string }
+
+/** The URI of a media resource is `harness-media://<threadId>/<id>`. */
+const MEDIA_URI_PREFIX = 'harness-media://'
+
+/** The biggest image or audio file that a result carries inline. */
+const INLINE_MEDIA_MAX_BYTES = 5 * 1024 * 1024
+
+const threadIdSchema: JSONSchema = {
+  type: 'string',
+  description:
+    'The conversation id. Leave it out to use the default conversation.',
+}
+
+const nameSchema: JSONSchema = {
+  type: 'string',
+  description: 'The file name. Optional.',
+}
+
+const attachmentsSchema: JSONSchema = {
+  type: 'array',
+  description: 'Files to send with the message.',
+  items: {
+    anyOf: [
+      {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+            description:
+              'A file path on the machine of the server. The file must be in a folder that the server allows.',
+          },
+          name: nameSchema,
+        },
+        required: ['path'],
+      },
+      {
+        type: 'object',
+        properties: {
+          url: {
+            type: 'string',
+            description:
+              'A URL of the file. The model reads it. The server does not download it.',
+          },
+          mimeType: {
+            type: 'string',
+            description:
+              'The MIME type, for example image/png. Needed when the URL does not end in a known file extension.',
+          },
+          name: nameSchema,
+        },
+        required: ['url'],
+      },
+      {
+        type: 'object',
+        properties: {
+          data: { type: 'string', description: 'The file bytes in base64.' },
+          mimeType: {
+            type: 'string',
+            description: 'The MIME type, for example image/png.',
+          },
+          name: nameSchema,
+        },
+        required: ['data', 'mimeType'],
+      },
+    ],
+  },
+}
+
+/**
+ * Serves a harness as an MCP server, so any MCP client (Claude Code, Claude
+ * Desktop, Cursor, another agent) can use it.
+ *
+ * The tools are `chat`, `steer`, `cancel`, `approve`, `reject`, `resolve`,
+ * `answer`, and `status`, plus `agent_<name>` for each agent in
+ * `harness.expose.agents` and `command_<name>` for each plugin command in
+ * `harness.expose.commands`.
+ * Every tool takes an optional `threadId`. Sessions open with
+ * `host.open(harness, { threadId })`.
+ *
+ * Each interrupt in a result has a `kind`: `approval`, `client-tool`, or
+ * `generic`. `approve` and `reject` answer approvals only. `resolve` answers
+ * every kind: `approved` for an approval, and `payload` for the others.
+ *
+ * `chat` takes `attachments`: `{ path }` (only inside `filePaths`),
+ * `{ url, mimeType? }` (the model reads the URL, the server does not fetch
+ * it), or `{ data, mimeType }` (base64). A result lists the media that the
+ * work made in `media`. An image or audio file up to 5 MB comes back inline.
+ * Any other file comes back as a `resource_link` to
+ * `harness-media://<threadId>/<id>`, which `resources/read` returns.
+ *
+ * The result is the server from `createMCPServer`. Mount `server.fetch` on
+ * an HTTP route, or pass the server to `serveMCPStdio`.
+ *
+ * @param options - The host, the harness, the default thread, the approval mode, and the folders for `path` attachments
+ *
+ * @example
+ * ```ts
+ * const server = await createHarnessMcpServer({ host, harness: assistant })
+ * serveMCPStdio(server)
+ * ```
+ */
+export async function createHarnessMcpServer(options: HarnessMcpServerOptions) {
+  const { host, harness } = options
+  const defaultThread = options.threadId ?? 'main'
+  const approvals = options.approvals ?? 'ask'
+  const filePaths = options.filePaths ?? []
+  // Work that stopped for a question, by question id. `answer` continues it.
+  const waiting = new Map<string, Operation<unknown>>()
+
+  const open = (args: unknown) =>
+    host.open(harness, {
+      threadId:
+        isRecord(args) && typeof args.threadId === 'string'
+          ? args.threadId
+          : defaultThread,
+    })
+
+  // Answers the approvals with the approval mode. `undefined` means that the
+  // client must answer. One resolve answers every interrupt, and only the
+  // client can answer an interrupt that is not an approval.
+  async function decide(interrupts: Array<Interrupt>, context: MCPToolContext) {
+    if (!interrupts.every(isApproval)) return undefined
+    if (approvals === 'auto') {
+      return interrupts.map((interrupt) => ({
+        interruptId: interrupt.id,
+        payload: true,
+      }))
+    }
+    const answers: Array<Answer> = []
+    for (const interrupt of interrupts) {
+      try {
+        const answer = await context.requestInput({
+          message: approvalQuestion(interrupt),
+        })
+        answers.push({ interruptId: interrupt.id, payload: isYes(answer) })
+      } catch {
+        // ponytail: no elicitation, a declined question, or spec 2026 (it runs
+        // the whole call again). The client answers with approve or reject.
+        return undefined
+      }
+    }
+    return answers
+  }
+
+  // Waits for the work. A chat turn that stops for approvals continues while
+  // the approval mode decides them. The result gets the media of the work.
+  async function finish(
+    session: HarnessSession,
+    work: Operation<unknown>,
+    workFrom: Cursor,
+    context: MCPToolContext,
+  ) {
+    let operation = work
+    let from = workFrom
+    // The media of every operation that this call waited for.
+    const media: Array<MediaRecord> = []
+    while (true) {
+      const outcome = await settle(session, operation, from)
+      if (!outcome.done) {
+        waiting.set(outcome.questionId, operation)
+        return { status: 'waiting', ...pending(session) }
+      }
+      media.push(...(await mediaOf(operation)))
+      if (operation.kind !== 'chat') {
+        return withMedia(session, outcome.value, media)
+      }
+      const interrupts = session.snapshot().pendingInterrupts
+      const stopped =
+        operation.status() === 'interrupted' && interrupts.length > 0
+      const answers = stopped ? await decide(interrupts, context) : undefined
+      if (answers === undefined) {
+        const result = {
+          status: operation.status(),
+          text: turnText(outcome.value),
+          ...pending(session),
+        }
+        return withMedia(session, result, media)
+      }
+      from = session.snapshot().cursor
+      operation = (await resolveAll(session, answers)).turn
+    }
+  }
+
+  async function resume(
+    session: HarnessSession,
+    answers: Array<Answer>,
+    context: MCPToolContext,
+  ) {
+    const from = session.snapshot().cursor
+    const { turn } = await resolveAll(session, answers)
+    return finish(session, turn, from, context)
+  }
+
+  async function decideAll(
+    args: unknown,
+    approved: boolean,
+    context: MCPToolContext,
+  ) {
+    const session = await open(args)
+    const interrupts = session.snapshot().pendingInterrupts
+    const other = interrupts.find((interrupt) => !isApproval(interrupt))
+    if (other !== undefined) {
+      throw new Error(`Use resolve: interrupt ${other.id} needs a payload.`)
+    }
+    if (interrupts.length === 0) throw new Error('No approvals are waiting.')
+    const answers = interrupts.map((interrupt) => ({
+      interruptId: interrupt.id,
+      payload: approved,
+    }))
+    return resume(session, answers, context)
+  }
+
+  const chat = toolDefinition({
+    name: 'chat',
+    description:
+      'Send a message to the harness and wait for its answer. While a turn runs, the message waits in the queue. The result has the answer text, the status, the interrupts and questions that wait for you, and the media that the turn made.',
+    inputSchema: withThreadId({
+      type: 'object',
+      properties: {
+        message: { type: 'string', description: 'The message.' },
+        attachments: attachmentsSchema,
+      },
+      required: ['message'],
+    }),
+  }).server<MCPToolContext>(async (args, ctx) => {
+    const session = await open(args)
+    const message = await userInputOf(session, args, filePaths)
+    const from = session.snapshot().cursor
+    const turn = session.prompt(message, { busy: 'queue' })
+    return finish(session, turn, from, ctx.context)
+  })
+
+  const steer = toolDefinition({
+    name: 'steer',
+    description:
+      'Add a message to the running turn. The model reads it at its next step. With no running turn, the message starts a new turn.',
+    inputSchema: withThreadId({
+      type: 'object',
+      properties: {
+        message: { type: 'string', description: 'The message.' },
+      },
+      required: ['message'],
+    }),
+  }).server(async (args) => (await open(args)).steer(textArg(args, 'message')))
+
+  const cancel = toolDefinition({
+    name: 'cancel',
+    description: 'Cancel the running turn.',
+    inputSchema: withThreadId(undefined),
+  }).server(async (args) => (await open(args)).cancel())
+
+  const approve = toolDefinition({
+    name: 'approve',
+    description:
+      'Approve every tool call that waits for approval, then wait for the turn to continue. When an interrupt of another kind also waits, use resolve.',
+    inputSchema: withThreadId(undefined),
+  }).server<MCPToolContext>(async (args, ctx) =>
+    decideAll(args, true, ctx.context),
+  )
+
+  const reject = toolDefinition({
+    name: 'reject',
+    description:
+      'Reject every tool call that waits for approval, then wait for the turn to continue. When an interrupt of another kind also waits, use resolve.',
+    inputSchema: withThreadId(undefined),
+  }).server<MCPToolContext>(async (args, ctx) =>
+    decideAll(args, false, ctx.context),
+  )
+
+  const resolve = toolDefinition({
+    name: 'resolve',
+    description:
+      'Answer every interrupt that waits, then wait for the turn to continue. Give one decision for each interrupt. For an approval, set approved. For a client tool, set payload to the tool output. For a generic interrupt, set payload to a value that matches its responseSchema.',
+    inputSchema: withThreadId({
+      type: 'object',
+      properties: {
+        decisions: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              interruptId: {
+                type: 'string',
+                description: 'The id of the interrupt.',
+              },
+              approved: {
+                type: 'boolean',
+                description:
+                  'For an approval: true runs the tool call, false rejects it.',
+              },
+              payload: {
+                description:
+                  'The answer. For a client tool, the tool output. For a generic interrupt, a value that matches its responseSchema.',
+              },
+            },
+            required: ['interruptId'],
+          },
+        },
+      },
+      required: ['decisions'],
+    }),
+  }).server<MCPToolContext>(async (args, ctx) => {
+    const session = await open(args)
+    const interrupts = session.snapshot().pendingInterrupts
+    const answers = answersOf(decisionsOf(args), interrupts)
+    return resume(session, answers, ctx.context)
+  })
+
+  const answer = toolDefinition({
+    name: 'answer',
+    description:
+      'Answer a question from the harness, then wait for the work that asked it.',
+    inputSchema: withThreadId({
+      type: 'object',
+      properties: {
+        questionId: { type: 'string', description: 'The id of the question.' },
+        value: { description: 'The answer. It matches the question schema.' },
+      },
+      required: ['questionId', 'value'],
+    }),
+  }).server<MCPToolContext>(async (args, ctx) => {
+    const session = await open(args)
+    const questionId = textArg(args, 'questionId')
+    const from = session.snapshot().cursor
+    const receipt = await session.answer({
+      questionId,
+      value: isRecord(args) ? args.value : undefined,
+    })
+    if (receipt.status === 'rejected') {
+      throw new Error(
+        `The harness refused the answer: ${receipt.reason ?? 'no reason'}.`,
+      )
+    }
+    const operation = waiting.get(questionId)
+    waiting.delete(questionId)
+    // A question that no tool call waits on: nothing to continue.
+    if (operation === undefined) {
+      return { status: 'answered', ...pending(session) }
+    }
+    return finish(session, operation, from, ctx.context)
+  })
+
+  const status = toolDefinition({
+    name: 'status',
+    description:
+      'Show what the harness does now: the status, the interrupts and questions that wait, the background agents, and the queued turns.',
+    inputSchema: withThreadId(undefined),
+  }).server(async (args) => {
+    const session = await open(args)
+    const snapshot = session.snapshot()
+    return {
+      status: snapshot.status,
+      ...pending(session),
+      agents: snapshot.activeOperations
+        .filter((operation) => operation.kind === 'agent')
+        .map(({ id, agent }) => ({ id, agent })),
+      queuedTurns: snapshot.queuedTurns,
+    }
+  })
+
+  // Agents and commands come from a session. Every thread has the same ones.
+  const session = await host.open(harness, { threadId: defaultThread })
+
+  const exposed: ReadonlyArray<string> = harness.expose?.agents ?? []
+  const agents = exposed.flatMap((name) => {
+    const agent = session.registry.get(name)
+    return agent === undefined
+      ? []
+      : [{ name, description: agent.description, agent }]
+  })
+  const agentTools = toolNames('agent', agents).map(
+    ({ item: { name, agent }, toolName, description }) =>
+      toolDefinition({
+        name: toolName,
+        description,
+        inputSchema: withThreadId(convertSchemaToJsonSchema(agent.inputSchema)),
+      }).server<MCPToolContext>(async (args, ctx) => {
+        const target = await open(args)
+        const handle = target.agent(name)
+        if (handle === undefined) throw new Error(`Unknown agent: ${name}`)
+        const from = target.snapshot().cursor
+        return finish(target, handle.start(inputOf(args)), from, ctx.context)
+      }),
+  )
+
+  // A command can change the session, for example `/mode bypass`, so an MCP
+  // client runs only the commands in `expose.commands`, like a protocol client.
+  const exposedCommands: ReadonlyArray<string> = harness.expose?.commands ?? []
+  const commands = session
+    .describe()
+    .commands.filter(({ name }) => exposedCommands.includes(name))
+  const commandTools = toolNames('command', commands).map(
+    ({ item: command, toolName, description }) =>
+      toolDefinition({
+        name: toolName,
+        description,
+        inputSchema: withThreadId(
+          isJsonSchema(command.input) ? command.input : undefined,
+        ),
+      }).server<MCPToolContext>(async (args, ctx) => {
+        const target = await open(args)
+        const from = target.snapshot().cursor
+        const operation = target.command(command.name, inputOf(args))
+        return finish(target, operation, from, ctx.context)
+      }),
+  )
+
+  // The bytes of a `resource_link` from a result. The link names its thread,
+  // and a thread reads only its own media.
+  const mediaResource = resourceDefinition({
+    uriTemplate: `${MEDIA_URI_PREFIX}{threadId}/{id}`,
+    name: 'media',
+    mimeType: 'application/octet-stream',
+    argsSchema: { parse: mediaAddress },
+  }).read(async (_uri, { threadId, id }) => {
+    const target = await host.open(harness, { threadId })
+    const record = await target.getMedia(id)
+    if (record === null) {
+      throw new Error(`Media ${id} was not found in thread ${threadId}.`)
+    }
+    const blob = toBase64(await target.loadMedia(id))
+    return { blob, mimeType: record.mimeType }
+  })
+
+  return createMCPServer({
+    name: options.name ?? harness.name,
+    version: options.version ?? '1.0.0',
+    // `approvals: 'ask'` asks by elicitation, and elicitation needs a spec 2025
+    // session. ponytail: memory sessions live in this process, like the
+    // harness sessions. Add a `sessions` option when a host runs many instances.
+    sessions: 'memory',
+    resources: [mediaResource],
+    tools: [
+      chat,
+      steer,
+      cancel,
+      approve,
+      reject,
+      resolve,
+      answer,
+      status,
+      ...agentTools,
+      ...commandTools,
+    ],
+  })
+}
+
+// The harness needs one resolve that answers every open interrupt. An async
+// function waits for an operation that it returns, so the turn is wrapped.
+async function resolveAll(session: HarnessSession, answers: Array<Answer>) {
+  const receipt = await session.resolve(
+    answers.map((answer) => ({ ...answer, status: 'resolved' })),
+  )
+  const operation =
+    receipt.operationId === undefined
+      ? undefined
+      : session.operation(receipt.operationId)
+  if (operation === undefined) {
+    throw new Error(
+      `The harness refused the decisions: ${receipt.reason ?? 'no reason'}.`,
+    )
+  }
+  return { turn: operation }
+}
+
+/**
+ * Waits for `operation`. Stops early when the session asks a question after
+ * `from`, because the work waits for that answer.
+ */
+async function settle(
+  session: HarnessSession,
+  operation: Operation<unknown>,
+  from: Cursor,
+) {
+  const stop = new AbortController()
+  const done = Promise.resolve(operation).then((value) => ({
+    done: true as const,
+    value,
+  }))
+  const asked = (async () => {
+    const questionId = await questionAfter(session, from, stop.signal)
+    // The feed closed without a question: only the work can end the wait.
+    if (questionId === undefined) return done
+    return { done: false as const, questionId }
+  })()
+  try {
+    return await Promise.race([done, asked])
+  } finally {
+    stop.abort()
+  }
+}
+
+async function questionAfter(
+  session: HarnessSession,
+  from: Cursor,
+  signal: AbortSignal,
+) {
+  const events = session.events({ from, signal })
+  for await (const entry of events) {
+    const event = entry.event
+    const isQuestion =
+      event.type === EventType.CUSTOM && event.name === HARNESS_EVENTS.question
+    if (!isQuestion || !isRecord(event.value)) continue
+    const questionId = event.value.questionId
+    if (typeof questionId === 'string') return questionId
+  }
+  return undefined
+}
+
+function pending(session: HarnessSession) {
+  const snapshot = session.snapshot()
+  return {
+    interrupts: snapshot.pendingInterrupts.map((interrupt) => ({
+      id: interrupt.id,
+      kind: interruptKind(interrupt),
+      tool: interrupt.metadata?.toolName,
+      args: interrupt.metadata?.input,
+      message: interrupt.message,
+      responseSchema: interrupt.responseSchema,
+    })),
+    questions: snapshot.pendingQuestions.map(({ questionId, ...question }) => ({
+      id: questionId,
+      ...question,
+    })),
+  }
+}
+
+/**
+ * The message of a `chat` call: the text alone, or the text and one part per
+ * attachment. A file goes into the media store of the thread first. A
+ * `MediaError` (too big, a type the harness does not take) stops the call.
+ */
+async function userInputOf(
+  session: HarnessSession,
+  args: unknown,
+  filePaths: ReadonlyArray<string>,
+) {
+  const message = textArg(args, 'message')
+  const attachments = attachmentsOf(args)
+  if (attachments.length === 0) return message
+  const parts: Array<ContentPart> = [{ type: 'text', content: message }]
+  for (const attachment of attachments) {
+    parts.push(await attachmentPart(session, attachment, filePaths))
+  }
+  return parts
+}
+
+function attachmentsOf(args: unknown) {
+  const list =
+    isRecord(args) && Array.isArray(args.attachments) ? args.attachments : []
+  const attachments = list.filter(isAttachment)
+  if (attachments.length !== list.length) {
+    throw new Error('Each attachment needs path, url, or data with mimeType.')
+  }
+  return attachments
+}
+
+async function attachmentPart(
+  session: HarnessSession,
+  attachment: Attachment,
+  filePaths: ReadonlyArray<string>,
+) {
+  if ('path' in attachment) {
+    const file = await readAllowedFile(attachment.path, filePaths)
+    const name = attachment.name ?? file.name
+    return mediaPart(
+      await session.putMedia(file.bytes, { mimeType: file.mimeType, name }),
+    )
+  }
+  if ('url' in attachment) return urlPart(attachment)
+  const bytes = Uint8Array.from(atob(attachment.data), (char) =>
+    char.charCodeAt(0),
+  )
+  const name = attachment.name ?? 'attachment'
+  return mediaPart(
+    await session.putMedia(bytes, { mimeType: attachment.mimeType, name }),
+  )
+}
+
+/**
+ * The bytes of `path` when its real path is inside one of `folders`. The real
+ * path follows every symlink and `..`, so neither can leave a folder. A
+ * missing file gets the same refusal, so a client cannot probe for files.
+ */
+async function readAllowedFile(path: string, folders: ReadonlyArray<string>) {
+  if (folders.length === 0) {
+    throw new Error(
+      'This server does not read files. Send the file as data or url.',
+    )
+  }
+  // Loaded here, not at the top: the module must also load where node:fs is
+  // missing (an edge worker), and only a path attachment needs it.
+  const { readFile, realpath } = await import('node:fs/promises')
+  const { basename, isAbsolute, relative, sep } = await import('node:path')
+  const refusal = `Cannot read ${path}. It must be a file inside the folders this server may read.`
+  const real = await realpath(path).catch(() => undefined)
+  if (real === undefined) throw new Error(refusal)
+  const roots = await Promise.all(folders.map((folder) => realpath(folder)))
+  const isInside = roots.some((root) => {
+    const rest = relative(root, real)
+    const isOut = rest === '..' || rest.startsWith(`..${sep}`)
+    return rest !== '' && !isOut && !isAbsolute(rest)
+  })
+  if (!isInside) throw new Error(refusal)
+  const name = basename(path)
+  const mimeType = mimeTypeOf(name)
+  if (mimeType === undefined) {
+    throw new Error(
+      `Unknown file type: ${name}. Send the file as data with its mimeType.`,
+    )
+  }
+  // ponytail: reads the whole file, and the store refuses it after that when
+  // it is over `media.maxBytes`. Stream it when big local files matter.
+  return { bytes: await readFile(real), mimeType, name }
+}
+
+/**
+ * A part that sends `attachment.url` to the model as it is. The server does
+ * not fetch it: a remote client must not make the server call an internal
+ * address. The kind comes from `mimeType`, or from the extension of the path.
+ */
+function urlPart(attachment: { url: string; mimeType?: string }) {
+  const { url } = attachment
+  const mimeType = attachment.mimeType ?? mimeTypeOf(new URL(url).pathname)
+  const kind = mimeType === undefined ? undefined : kindOf(mimeType)
+  if (mimeType === undefined || kind === undefined) {
+    throw new Error(`Cannot tell the kind of ${url}. Add its mimeType.`)
+  }
+  const part: ContentPart = {
+    type: kind,
+    source: { type: 'url', value: url, mimeType },
+  }
+  return part
+}
+
+/** The media records that the settled `operation` published, in order. */
+async function mediaOf(operation: Operation<unknown>) {
+  const records: Array<MediaRecord> = []
+  // The operation is settled, so its stream replays its events, then ends.
+  const events = operation.stream()
+  for await (const event of events) {
+    const isMedia =
+      event.type === EventType.CUSTOM && event.name === HARNESS_EVENTS.media
+    if (isMedia && isMediaRecord(event.value)) records.push(event.value)
+  }
+  return records
+}
+
+/**
+ * The tool result of `value` with its media. Without media, `value` stays as
+ * it is. An object result also lists the media in `media`. Each file then
+ * follows the JSON text as its own content block.
+ */
+async function withMedia(
+  session: HarnessSession,
+  value: unknown,
+  media: Array<MediaRecord>,
+) {
+  if (media.length === 0) return value
+  const listed = media.map((record) => ({
+    id: record.id,
+    kind: record.kind,
+    name: record.name,
+    mimeType: record.mimeType,
+    size: record.size,
+    uri: mediaUri(record),
+  }))
+  const blocks = await Promise.all(
+    media.map((record) => mediaBlock(session, record)),
+  )
+  const result = toCallToolResult(
+    isRecord(value) ? { ...value, media: listed } : value,
+  )
+  return { ...result, content: [...result.content, ...blocks] }
+}
+
+/** Image and audio up to 5 MB go inline. Anything else goes as a link. */
+async function mediaBlock(session: HarnessSession, record: MediaRecord) {
+  const { kind } = record
+  const isSmall = record.size <= INLINE_MEDIA_MAX_BYTES
+  if (isSmall && (kind === 'image' || kind === 'audio')) {
+    const data = toBase64(await session.loadMedia(record.id))
+    const inline: ContentBlock = { type: kind, data, mimeType: record.mimeType }
+    return inline
+  }
+  const link: ContentBlock = {
+    type: 'resource_link',
+    uri: mediaUri(record),
+    name: record.name,
+    mimeType: record.mimeType,
+  }
+  return link
+}
+
+function mediaUri(record: MediaRecord) {
+  const threadId = encodeURIComponent(record.threadId)
+  return `${MEDIA_URI_PREFIX}${threadId}/${encodeURIComponent(record.id)}`
+}
+
+/**
+ * The thread and media id of a `harness-media://<threadId>/<id>` URI, from
+ * the template variables. `mediaUri` encodes both, so they are decoded here.
+ */
+function mediaAddress(variables: unknown) {
+  const threadId = isRecord(variables) ? variables.threadId : undefined
+  const id = isRecord(variables) ? variables.id : undefined
+  if (typeof threadId !== 'string' || typeof id !== 'string') {
+    throw new Error('A media URI is harness-media://<threadId>/<id>.')
+  }
+  return {
+    threadId: decodeURIComponent(threadId),
+    id: decodeURIComponent(id),
+  }
+}
+
+// ponytail: the same as `toBase64` in `@tanstack/ai-harness/src/media.ts`,
+// which the package does not export. `btoa`, not `Buffer`, for edge workers.
+function toBase64(bytes: Uint8Array) {
+  const chunk = 0x8000
+  let binary = ''
+  // Chunks keep `fromCharCode` under the engine's argument limit.
+  for (let offset = 0; offset < bytes.length; offset += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + chunk))
+  }
+  return btoa(binary)
+}
+
+/**
+ * How the client answers `interrupt`. `chat()` puts a binding on each
+ * interrupt. The binding marks a tool approval (answer with `approved`) and a
+ * client tool (answer with the tool output). Any other interrupt is generic:
+ * answer with a value that matches its `responseSchema`.
+ */
+function interruptKind(interrupt: Interrupt) {
+  const binding = readUnopenedInterruptBinding(interrupt)
+  switch (binding?.kind) {
+    case 'tool-approval':
+      return 'approval'
+    case 'client-tool-execution':
+      return 'client-tool'
+    case 'generic':
+    case undefined:
+      return 'generic'
+  }
+}
+
+function isApproval(interrupt: Interrupt) {
+  return interruptKind(interrupt) === 'approval'
+}
+
+/**
+ * The answers of a `resolve` call. The decisions must answer every open
+ * interrupt, and only those. An approval takes `approved` (or `payload`).
+ * Every other interrupt takes `payload`.
+ */
+function answersOf(decisions: Array<Decision>, interrupts: Array<Interrupt>) {
+  const openIds = interrupts.map(({ id }) => id)
+  const decidedIds = decisions.map(({ interruptId }) => interruptId)
+  const missing = openIds.filter((id) => !decidedIds.includes(id))
+  if (missing.length > 0) {
+    throw new Error(
+      `resolve must answer every open interrupt. Missing: ${missing.join(', ')}.`,
+    )
+  }
+  const unknown = decidedIds.filter((id) => !openIds.includes(id))
+  if (unknown.length > 0) {
+    throw new Error(`These interrupts are not open: ${unknown.join(', ')}.`)
+  }
+  const approvalIds = interrupts.filter(isApproval).map(({ id }) => id)
+  return decisions.map(({ interruptId, approved, payload }) => {
+    if (approvalIds.includes(interruptId)) {
+      const answer = approved ?? payload
+      if (answer === undefined) {
+        throw new Error(
+          `The decision for ${interruptId} needs approved or payload.`,
+        )
+      }
+      return { interruptId, payload: answer }
+    }
+    if (payload === undefined) {
+      throw new Error(
+        `The decision for ${interruptId} needs a payload. It is not an approval.`,
+      )
+    }
+    return { interruptId, payload }
+  })
+}
+
+function approvalQuestion(interrupt: Interrupt) {
+  const args = interrupt.metadata?.input
+  const shown = args === undefined ? '' : ` Arguments: ${JSON.stringify(args)}.`
+  const message = interrupt.message ?? 'A tool call needs approval'
+  return `${message}.${shown} Approve? Answer yes or no.`
+}
+
+function isYes(answer: unknown) {
+  return typeof answer === 'string' && /^y(es)?$/i.test(answer.trim())
+}
+
+function turnText(value: unknown) {
+  return isRecord(value) && typeof value.text === 'string' ? value.text : ''
+}
+
+/**
+ * Gives each item an MCP tool name, in name order. MCP tool names allow
+ * letters, digits, and underscores, so `connect:notion` becomes
+ * `command_connect_notion`. `connect_notion` then gets the same name, so the
+ * later one gets a number: `command_connect_notion_2`. Each tool of such a
+ * clash names its original name in the description.
+ */
+function toolNames<TItem extends { name: string; description: string }>(
+  prefix: string,
+  items: ReadonlyArray<TItem>,
+) {
+  const safeName = (name: string) =>
+    `${prefix}_${name.replace(/[^A-Za-z0-9_]/g, '_')}`
+  const sorted = [...items].sort(byName)
+  const safeNames = sorted.map((item) => safeName(item.name))
+  const used = new Set<string>()
+  return sorted.map((item) => {
+    const base = safeName(item.name)
+    let toolName = base
+    for (let count = 2; used.has(toolName); count++) {
+      toolName = `${base}_${count}`
+    }
+    used.add(toolName)
+    const isShared = safeNames.filter((other) => other === base).length > 1
+    const clashes = isShared || toolName !== base
+    const description = clashes
+      ? `${item.description} (${prefix} ${item.name})`
+      : item.description
+    return { item, toolName, description }
+  })
+}
+
+// Code unit order, so the order is the same in every locale.
+function byName(left: { name: string }, right: { name: string }) {
+  if (left.name === right.name) return 0
+  return left.name < right.name ? -1 : 1
+}
+
+function withThreadId(schema: JSONSchema | undefined) {
+  return {
+    ...schema,
+    type: 'object',
+    properties: { ...schema?.properties, threadId: threadIdSchema },
+  }
+}
+
+// The tool input without `threadId`, or `undefined` when nothing is left.
+function inputOf(args: unknown) {
+  if (!isRecord(args)) return undefined
+  const entries = Object.entries(args).filter(([key]) => key !== 'threadId')
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined
+}
+
+function textArg(args: unknown, key: string) {
+  const value = isRecord(args) ? args[key] : undefined
+  if (typeof value !== 'string') throw new Error(`${key} must be a string.`)
+  return value
+}
+
+function decisionsOf(args: unknown) {
+  const list =
+    isRecord(args) && Array.isArray(args.decisions) ? args.decisions : []
+  return list.filter(isDecision)
+}
+
+function isDecision(value: unknown): value is Decision {
+  return (
+    isRecord(value) &&
+    typeof value.interruptId === 'string' &&
+    (value.approved === undefined || typeof value.approved === 'boolean')
+  )
+}
+
+function isAttachment(value: unknown): value is Attachment {
+  if (!isRecord(value) || !isOptionalString(value.name)) return false
+  if (typeof value.path === 'string') return true
+  if (typeof value.url === 'string') return isOptionalString(value.mimeType)
+  return typeof value.data === 'string' && typeof value.mimeType === 'string'
+}
+
+function isOptionalString(value: unknown) {
+  return value === undefined || typeof value === 'string'
+}
+
+// `session.describe()` gives each command input as JSON Schema.
+function isJsonSchema(value: unknown): value is JSONSchema {
+  return isRecord(value)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
diff --git a/packages/ai-mcp/src/tools.ts b/packages/ai-mcp/src/tools.ts
index d0365f7a3d..1418c046b6 100644
--- a/packages/ai-mcp/src/tools.ts
+++ b/packages/ai-mcp/src/tools.ts
@@ -147,6 +147,8 @@ export function mcpContentToTanstack(
  * @param signal - Stops the wait when the caller aborts
  * @param inputResponse - The user's answer from an `mcp_input` interrupt
  * @param requestOptions - The client `requestOptions`, sent with tools/call
+ * @param askInput - Asks the user for each elicitation round on spec 2026.
+ *   The harness sets it. Without it, a call answers one round.
  */
 export async function callMcpTool(
   client: Client,
@@ -156,6 +158,7 @@ export async function callMcpTool(
   signal?: AbortSignal,
   inputResponse?: ToolInputResponse,
   requestOptions?: MCPClientOptions['requestOptions'],
+  askInput?: AskInput,
 ) {
   signal?.throwIfAborted()
   const isModern = client.getProtocolEra() === 'modern'
@@ -194,16 +197,44 @@ export async function callMcpTool(
     // ponytail: one input round per call. The next resume starts with no
     // requestState, so a second pause would ask round 1 again forever.
     // Carry requestState through the interrupt if servers need more rounds.
-    if (isInputRequiredResult(raw)) {
+    if (isInputRequiredResult(raw) && askInput === undefined) {
       throw new Error(
         `The MCP tool "${mcpName}" asked for input a second time. ` +
           'This client answers one input request per tool call.',
       )
     }
   }
+  // The harness asks the user for each elicitation round, up to a cap.
+  for (
+    let round = 1;
+    isModern && askInput && isInputRequiredResult(raw);
+    round++
+  ) {
+    const entry = firstInputRequest(raw.inputRequests)
+    if (entry?.method !== 'elicitation/create') break
+    if (round > maxInputRounds) {
+      throw new Error(
+        `The MCP tool "${mcpName}" asked for input more than ` +
+          `${maxInputRounds} times in one call.`,
+      )
+    }
+    const answer = await askInput(isRecord(entry.params) ? entry.params : entry)
+    raw = await rawRequest(
+      client,
+      'tools/call',
+      { ...params, ...retryParams(raw, answer) },
+      signal,
+      requestOptions,
+    )
+  }
   return finishToolCall(client, mcpName, raw, signal)
 }
 
+/** Asks the user for one MCP elicitation request body. */
+export type AskInput = (request: unknown) => Promise<ToolInputResponse>
+
+const maxInputRounds = 5
+
 // Answers only the first input request. That is the one the interrupt shows.
 function retryParams(
   result: { inputRequests?: unknown; requestState?: string },
@@ -684,7 +715,11 @@ export function makeMcpExecute(
 ) {
   return async (
     args: unknown,
-    ctx?: { abortSignal?: AbortSignal; inputResponse?: ToolInputResponse },
+    ctx?: {
+      abortSignal?: AbortSignal
+      inputResponse?: ToolInputResponse
+      askInput?: AskInput
+    },
   ) => {
     const result = await callMcpTool(
       client,
@@ -694,6 +729,7 @@ export function makeMcpExecute(
       ctx?.abortSignal,
       ctx?.inputResponse,
       requestOptions,
+      ctx?.askInput,
     )
     if (result.isError) {
       const text = Array.isArray(result.content)
diff --git a/packages/ai-mcp/tests/connector-edges.test.ts b/packages/ai-mcp/tests/connector-edges.test.ts
new file mode 100644
index 0000000000..dc62118e9a
--- /dev/null
+++ b/packages/ai-mcp/tests/connector-edges.test.ts
@@ -0,0 +1,567 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { EventType } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import {
+  HARNESS_EVENTS,
+  createHarnessHost,
+  defineHarness,
+} from '@tanstack/ai-harness'
+import { mcpConnector } from '../src/connector'
+import { approveSignIns, recorder } from './connector-helpers'
+import { startProtectedServer } from './protected-server'
+import type { Credential } from '@tanstack/ai-persistence'
+import type {
+  HarnessHost,
+  HarnessSession,
+  SessionEvent,
+} from '@tanstack/ai-harness'
+
+const scope = { threadId: 't', userId: 'user-1' }
+const cleanups: Array<() => unknown> = []
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0).reverse()) await cleanup()
+})
+
+async function setup(
+  credential?: Credential,
+  serverOptions?: Parameters<typeof startProtectedServer>[0],
+) {
+  const server = await startProtectedServer(serverOptions)
+  cleanups.push(() => server.close())
+  const persistence = memoryPersistence()
+  if (credential)
+    await persistence.stores.credentials.set({ scope, id: 'demo', credential })
+  const host = createHarnessHost({ persistence })
+  cleanups.push(() => host.close())
+  return { server, persistence, host }
+}
+
+/** A harness with only the `demo` connector, with default options. */
+function connectorHarness(url: string, model: ReturnType<typeof recorder>) {
+  return defineHarness({
+    name: 'test/connector',
+    adapter: model.adapter,
+    plugins: () => [mcpConnector({ id: 'demo', label: 'Demo', url })],
+  })
+}
+
+/** Open a session of {@link connectorHarness} for `user-1`. */
+function openDemo(
+  host: HarnessHost,
+  url: string,
+  model = recorder(),
+  threadId = 't',
+) {
+  return host.open(connectorHarness(url, model), {
+    threadId,
+    principal: { id: 'user-1' },
+  })
+}
+
+/** Run one prompt and return every event the session published for it. */
+async function promptAndCollect(session: HarnessSession, text: string) {
+  const seen: Array<SessionEvent> = []
+  const controller = new AbortController()
+  const reading = (async () => {
+    for await (const entry of session.events({
+      from: '0',
+      signal: controller.signal,
+    }))
+      seen.push(entry)
+  })()
+  await session.prompt(text)
+  controller.abort()
+  await reading
+  return seen
+}
+
+/** The values of the custom events named `name`, in order. */
+function customValues(seen: Array<SessionEvent>, name: string) {
+  return seen.flatMap(({ event }) =>
+    event.type === EventType.CUSTOM && event.name === name ? [event.value] : [],
+  )
+}
+
+describe('mcpConnector with a saved sign-in', () => {
+  it('uses the saved token and client after a restart, without /connect', async () => {
+    const { server, host } = await setup({
+      type: 'oauth',
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+      expiresAt: Date.now() + 3_600_000,
+      client: {
+        clientId: 'client-1',
+        clientSecret: 'secret-1',
+        redirectUri: 'http://127.0.0.1:1/callback',
+      },
+    })
+    const model = recorder('demo_echo')
+    const session = await openDemo(host, server.url, model)
+    await session.prompt('echo')
+    expect(model.toolNames(0)).toEqual(['demo_echo'])
+    expect(JSON.stringify(model.calls[1]?.messages)).toContain('echo: hi')
+    // The status prompt is empty once connected.
+    expect(JSON.stringify(model.calls[0]?.systemPrompts ?? [])).not.toContain(
+      'is not connected',
+    )
+    expect(server.seen.registrations).toHaveLength(0)
+  })
+
+  it.each([
+    {
+      redirect: 'the saved client redirect URI',
+      client: { clientId: 'client-1', redirectUri: 'http://127.0.0.1:1/cb' },
+      redirectUri: 'http://127.0.0.1:1/cb',
+    },
+    {
+      redirect: 'the fallback redirect URI',
+      client: { clientId: 'client-1' },
+      redirectUri: 'http://127.0.0.1/callback',
+    },
+  ])(
+    'refreshes an expired token with $redirect and keeps the old refresh token and client',
+    async ({ client, redirectUri }) => {
+      const { server, persistence, host } = await setup({
+        type: 'oauth',
+        accessToken: 'stale',
+        refreshToken: 'refresh-1',
+        expiresAt: Date.now() - 1000,
+        client,
+      })
+      const model = recorder('demo_echo')
+      const session = await openDemo(host, server.url, model)
+      await session.prompt('echo')
+      expect(model.toolNames(0)).toEqual(['demo_echo'])
+      expect(
+        server.seen.tokenRequests.map((form) => form.get('grant_type')),
+      ).toEqual(['refresh_token'])
+      expect(server.seen.registrations).toHaveLength(0)
+      // A sign-in saved without an issuer gets the issuer of this server.
+      expect(
+        await persistence.stores.credentials.get({ scope, id: 'demo' }),
+      ).toEqual({
+        type: 'oauth',
+        accessToken: 'access-2',
+        refreshToken: 'refresh-1',
+        client: { clientId: 'client-1', redirectUri, issuer: server.issuer },
+      })
+    },
+  )
+
+  it.each([
+    {
+      failure: 'the refresh token is revoked',
+      credential: {
+        type: 'oauth',
+        accessToken: 'stale',
+        refreshToken: 'revoked',
+      },
+      revoke: [],
+      // The server refused the refresh token, so it is deleted.
+      kept: null,
+    },
+    {
+      failure: 'the server revokes a token that has no refresh token',
+      credential: { type: 'oauth', accessToken: 'access-1' },
+      revoke: ['access-1'],
+      kept: 'access-1',
+    },
+  ] satisfies Array<{
+    failure: string
+    credential: Credential
+    revoke: Array<string>
+    kept: string | null
+  }>)(
+    'drops the tools and asks the user to run /connect when $failure',
+    async ({ credential, revoke, kept }) => {
+      const { server, persistence, host } = await setup(credential)
+      for (const token of revoke) server.revoke(token)
+      const model = recorder()
+      const session = await openDemo(host, server.url, model)
+      const seen = await promptAndCollect(session, 'hi')
+      expect(model.toolNames(0)).toEqual([])
+      expect(customValues(seen, 'harness.plugin.warning')).toEqual([
+        {
+          plugin: 'connector/demo',
+          message: 'Sign in to demo first. Run /connect demo.',
+        },
+      ])
+      // The notice has no URL: outside /connect, no browser sign-in starts.
+      expect(customValues(seen, HARNESS_EVENTS.authRequired)).toEqual([
+        { connector: 'demo' },
+      ])
+      // The same turn tells the model that the user must run /connect.
+      expect(JSON.stringify(model.calls[0]?.systemPrompts)).toContain(
+        'run /connect demo',
+      )
+      const saved = await persistence.stores.credentials.get({
+        scope,
+        id: 'demo',
+      })
+      expect(saved?.type === 'oauth' ? saved.accessToken : null).toBe(kept)
+    },
+  )
+
+  it('keeps the sign-in and a connection error when the network is down', async () => {
+    const { server, persistence, host } = await setup({
+      type: 'oauth',
+      accessToken: 'access-1',
+    })
+    const model = recorder()
+    const session = await host.open(
+      defineHarness({
+        name: 'test/offline',
+        adapter: model.adapter,
+        plugins: () => [
+          mcpConnector({
+            id: 'demo',
+            label: 'Demo',
+            url: server.url,
+            // Each request fails the way `fetch` fails without a network.
+            fetch: async () => {
+              throw new TypeError('fetch failed')
+            },
+          }),
+        ],
+      }),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+    const seen = await promptAndCollect(session, 'hi')
+    expect(model.toolNames(0)).toEqual([])
+    expect(customValues(seen, 'harness.plugin.warning')).toEqual([
+      { plugin: 'connector/demo', message: 'Failed to connect to MCP server' },
+    ])
+    expect(customValues(seen, HARNESS_EVENTS.authRequired)).toEqual([])
+    expect(JSON.stringify(model.calls[0]?.systemPrompts ?? [])).not.toContain(
+      'is not connected',
+    )
+    expect(
+      await persistence.stores.credentials.get({ scope, id: 'demo' }),
+    ).toEqual({
+      type: 'oauth',
+      accessToken: 'access-1',
+    })
+  })
+})
+
+describe('mcpConnector /connect', () => {
+  it('asks for scopes, shows the client name, and uses the prefix and approval rule', async () => {
+    const { server, persistence, host } = await setup()
+    const model = recorder()
+    const session = await host.open(
+      defineHarness({
+        name: 'test/options',
+        adapter: model.adapter,
+        plugins: () => [
+          mcpConnector({
+            id: 'demo',
+            label: 'Demo',
+            url: server.url,
+            prefix: 'd',
+            scopes: ['read'],
+            clientName: 'Acme Agent',
+            needsApproval: () => true,
+            fetch: (input, init) => fetch(input, init),
+          }),
+        ],
+      }),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+    const browser = approveSignIns(session, 'code-1')
+    cleanups.push(browser.stop)
+
+    expect(await session.command('connect:demo')).toBe('Connected to Demo.')
+    expect(browser.authorizationUrls[0]?.searchParams.get('scope')).toBe('read')
+    expect(server.seen.registrations[0]).toMatchObject({
+      client_name: 'Acme Agent',
+      scope: 'read',
+    })
+    expect(
+      await persistence.stores.credentials.get({ scope, id: 'demo' }),
+    ).toMatchObject({
+      scopes: ['read', 'write'],
+      client: {
+        clientId: 'client-1',
+        redirectUri: expect.stringContaining('127.0.0.1'),
+      },
+    })
+
+    await session.prompt('hi')
+    expect(model.toolNames(0)).toEqual(['d_echo'])
+    expect(model.calls[0]?.tools?.[0]?.needsApproval).toBe(true)
+  })
+
+  it.each([
+    { before: 'no earlier sign-in', earlier: undefined },
+    {
+      before: 'an earlier sign-in',
+      // Maybe another account, with a larger scope. None of it may stay.
+      earlier: {
+        type: 'oauth',
+        accessToken: 'old',
+        refreshToken: 'refresh-0',
+        expiresAt: Date.now() + 3_600_000,
+        scopes: ['admin'],
+        client: { clientId: 'client-0', redirectUri: 'http://127.0.0.1:1/cb' },
+      },
+    },
+  ] satisfies Array<{ before: string; earlier: Credential | undefined }>)(
+    'saves only the new sign-in, which gives no refresh token, after $before',
+    async ({ earlier }) => {
+      const { persistence, host, server } = await setup(earlier)
+      const session = await openDemo(host, server.url)
+      const browser = approveSignIns(session, 'code-2')
+      cleanups.push(browser.stop)
+
+      expect(await session.command('connect:demo')).toBe('Connected to Demo.')
+      expect(
+        await persistence.stores.credentials.get({ scope, id: 'demo' }),
+      ).toEqual({
+        type: 'oauth',
+        accessToken: 'access-1',
+        client: {
+          clientId: 'client-1',
+          redirectUri: expect.stringMatching(/^http:\/\/127\.0\.0\.1:\d+\//),
+          issuer: server.issuer,
+        },
+      })
+    },
+  )
+
+  it('saves the issuer, and signs in and refreshes without SEP-2352 warnings', async () => {
+    // The SDK prints its SEP-2352 warnings with console.warn.
+    const warn = vi.spyOn(console, 'warn')
+    cleanups.push(() => warn.mockRestore())
+    const { server, persistence, host } = await setup()
+    const model = recorder()
+    const session = await openDemo(host, server.url, model)
+    const browser = approveSignIns(session, 'code-1')
+    cleanups.push(browser.stop)
+    expect(await session.command('connect:demo')).toBe('Connected to Demo.')
+
+    // The server stops taking the first token, so the next turn refreshes it.
+    server.revoke('access-1')
+    await session.prompt('hi')
+    expect(model.toolNames(0)).toEqual(['demo_echo'])
+    expect(
+      server.seen.tokenRequests.map((form) => form.get('grant_type')),
+    ).toEqual(['authorization_code', 'refresh_token'])
+    expect(
+      await persistence.stores.credentials.get({ scope, id: 'demo' }),
+    ).toMatchObject({
+      accessToken: 'access-2',
+      refreshToken: 'refresh-1',
+      client: { clientId: 'client-1', issuer: server.issuer },
+    })
+    const warnings = warn.mock.calls.map(([message]) => String(message))
+    expect(warnings.filter((message) => message.includes('SEP-2352'))).toEqual(
+      [],
+    )
+  })
+
+  it('passes the iss of the callback on, for a server that sends one (RFC 9207)', async () => {
+    const { server, persistence, host } = await setup(undefined, {
+      issParameter: true,
+    })
+    const session = await openDemo(host, server.url, recorder())
+    const browser = approveSignIns(session, 'code-1', server.issuer)
+    cleanups.push(browser.stop)
+    expect(await session.command('connect:demo')).toBe('Connected to Demo.')
+    expect(
+      await persistence.stores.credentials.get({ scope, id: 'demo' }),
+    ).toMatchObject({ accessToken: 'access-1' })
+  })
+
+  it.each([
+    { before: 'no sign-in', earlier: undefined, tools: [], asks: true },
+    {
+      before: 'the earlier sign-in',
+      earlier: {
+        type: 'oauth',
+        accessToken: 'access-1',
+        refreshToken: 'refresh-1',
+        client: { clientId: 'client-1', redirectUri: 'http://127.0.0.1:1/cb' },
+      },
+      tools: ['demo_echo'],
+      asks: false,
+    },
+  ] satisfies Array<{
+    before: string
+    earlier: Credential | undefined
+    tools: Array<string>
+    asks: boolean
+  }>)(
+    'keeps $before when a new sign-in fails',
+    async ({ earlier, tools, asks }) => {
+      const { persistence, host, server } = await setup(earlier)
+      const model = recorder()
+      const session = await openDemo(host, server.url, model)
+      const browser = approveSignIns(session, 'wrong-code')
+      cleanups.push(browser.stop)
+
+      await expect(session.command('connect:demo')).rejects.toMatchObject({
+        code: 'invalid_grant',
+      })
+      expect(
+        await persistence.stores.credentials.get({ scope, id: 'demo' }),
+      ).toEqual(earlier ?? null)
+      await session.prompt('hi')
+      expect(model.toolNames(0)).toEqual(tools)
+      expect(
+        JSON.stringify(model.calls[0]?.systemPrompts ?? []).includes(
+          'run /connect demo',
+        ),
+      ).toBe(asks)
+    },
+  )
+})
+
+describe('mcpConnector stored credential shapes', () => {
+  it('works with a bare token, reuses the tools, and signs out before any tool call', async () => {
+    const { server, persistence, host } = await setup({
+      type: 'oauth',
+      accessToken: 'access-1',
+    })
+    const model = recorder()
+    const session = await openDemo(host, server.url, model)
+    await session.prompt('one')
+    await session.prompt('two')
+    expect(model.toolNames(0)).toEqual(['demo_echo'])
+    expect(model.toolNames(1)).toEqual(['demo_echo'])
+
+    const fresh = await openDemo(host, server.url, recorder(), 't2')
+    expect(await fresh.command('disconnect:demo')).toBe(
+      'Disconnected from Demo.',
+    )
+    expect(
+      await persistence.stores.credentials.get({ scope, id: 'demo' }),
+    ).toBeNull()
+  })
+
+  it('refreshes a token saved without a client, and keeps a client secret', async () => {
+    const bare = await setup({
+      type: 'oauth',
+      accessToken: 'stale',
+      refreshToken: 'refresh-1',
+    })
+    const model = recorder()
+    const session = await openDemo(bare.host, bare.server.url, model)
+    await session.prompt('hi')
+    expect(model.toolNames(0)).toEqual(['demo_echo'])
+    const saved = await bare.persistence.stores.credentials.get({
+      scope,
+      id: 'demo',
+    })
+    expect(saved).toMatchObject({
+      accessToken: 'access-2',
+      refreshToken: 'refresh-1',
+    })
+    // No saved client: the SDK registered one before it refreshed.
+    expect(bare.server.seen.registrations).toHaveLength(1)
+    expect(saved).toMatchObject({ client: { clientId: 'client-1' } })
+
+    const withSecret = await setup({
+      type: 'oauth',
+      accessToken: 'stale',
+      refreshToken: 'refresh-1',
+      client: { clientId: 'client-1', clientSecret: 'secret-1' },
+    })
+    const other = await openDemo(withSecret.host, withSecret.server.url)
+    await other.prompt('hi')
+    expect(
+      await withSecret.persistence.stores.credentials.get({
+        scope,
+        id: 'demo',
+      }),
+    ).toMatchObject({
+      accessToken: 'access-2',
+      client: { clientId: 'client-1', clientSecret: 'secret-1' },
+    })
+  })
+
+  it('treats a saved API key as no sign-in for the MCP server', async () => {
+    const { server, host } = await setup({
+      type: 'api_key',
+      value: 'not-oauth',
+    })
+    const model = recorder()
+    const session = await openDemo(host, server.url, model)
+    await session.prompt('hi')
+    expect(model.toolNames(0)).toEqual([])
+  })
+})
+
+describe('mcpConnector client options', () => {
+  it('names the tools with toolName', async () => {
+    const { server, host } = await setup({
+      type: 'oauth',
+      accessToken: 'access-1',
+    })
+    const model = recorder()
+    const session = await host.open(
+      defineHarness({
+        name: 'test/tool-name',
+        adapter: model.adapter,
+        plugins: () => [
+          mcpConnector({
+            id: 'demo',
+            label: 'Demo',
+            url: server.url,
+            toolName: (tool) => `mcp__demo__${tool.name}`,
+          }),
+        ],
+      }),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+    await session.prompt('hi')
+    expect(model.toolNames(0)).toEqual(['mcp__demo__echo'])
+  })
+
+  it('sends requestOptions with each MCP request', async () => {
+    const { server, host } = await setup({
+      type: 'oauth',
+      accessToken: 'access-1',
+    })
+    const model = recorder()
+    const held: Array<Promise<Response>> = []
+    const session = await host.open(
+      defineHarness({
+        name: 'test/request-options',
+        adapter: model.adapter,
+        plugins: () => [
+          mcpConnector({
+            id: 'demo',
+            label: 'Demo',
+            url: server.url,
+            requestOptions: { timeout: 50 },
+            // Hold the tools/list answer for 500 ms, so only the 50 ms
+            // timeout can end that request.
+            fetch: (input, init) => {
+              const response = fetch(input, init)
+              const body = init?.body
+              if (typeof body !== 'string' || !body.includes('"tools/list"')) {
+                return response
+              }
+              const late = new Promise<void>((resolve) => {
+                setTimeout(resolve, 500)
+              }).then(() => response)
+              held.push(late)
+              return late
+            },
+          }),
+        ],
+      }),
+      { threadId: 't', principal: { id: 'user-1' } },
+    )
+    const seen = await promptAndCollect(session, 'hi')
+    // Let the held answer finish before the server closes.
+    await Promise.allSettled(held)
+    expect(model.toolNames(0)).toEqual([])
+    expect(customValues(seen, 'harness.plugin.warning')).toEqual([
+      {
+        plugin: 'connector/demo',
+        message: expect.stringContaining('timed out'),
+      },
+    ])
+  })
+})
diff --git a/packages/ai-mcp/tests/connector-helpers.ts b/packages/ai-mcp/tests/connector-helpers.ts
new file mode 100644
index 0000000000..d7ce558e12
--- /dev/null
+++ b/packages/ai-mcp/tests/connector-helpers.ts
@@ -0,0 +1,246 @@
+import { z } from 'zod'
+import {
+  McpServer,
+  WebStandardStreamableHTTPServerTransport,
+  createMcpHandler,
+  inputRequired,
+} from '@modelcontextprotocol/server'
+import { EventType } from '@tanstack/ai'
+import { HARNESS_EVENTS } from '@tanstack/ai-harness'
+import type {
+  ElicitRequestFormParams,
+  ElicitRequestURLParams,
+  InputRequest,
+} from '@modelcontextprotocol/server'
+import type { AnyTextAdapter, StreamChunk, TextOptions } from '@tanstack/ai'
+import type { HarnessSession } from '@tanstack/ai-harness'
+
+/** A text adapter for the connector tests. Only `chatStream` changes. */
+export function mockTextAdapter(chatStream: AnyTextAdapter['chatStream']) {
+  const adapter: AnyTextAdapter = {
+    kind: 'text',
+    name: 'mock',
+    model: 'mock',
+    '~types': {
+      providerOptions: {},
+      inputModalities: ['text'],
+      messageMetadataByModality: {
+        text: undefined,
+        image: undefined,
+        audio: undefined,
+        video: undefined,
+        document: undefined,
+      },
+      toolCapabilities: [],
+      toolCallMetadata: undefined,
+      systemPromptMetadata: undefined,
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+    chatStream,
+  }
+  return adapter
+}
+
+/** A model that records the calls it gets, calls `tool` once, then stops. */
+export function recorder(tool?: string) {
+  const calls: Array<TextOptions> = []
+  const now = () => Date.now()
+  const adapter = mockTextAdapter((options) => {
+    calls.push(options)
+    const first = calls.length === 1 && tool !== undefined
+    return (async function* (): AsyncGenerator<StreamChunk> {
+      yield {
+        type: EventType.RUN_STARTED,
+        runId: 'r',
+        threadId: 't',
+        timestamp: now(),
+      }
+      if (first) {
+        yield {
+          type: EventType.TOOL_CALL_START,
+          toolCallId: 'c1',
+          toolCallName: tool,
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.TOOL_CALL_ARGS,
+          toolCallId: 'c1',
+          delta: '{"text":"hi"}',
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.TOOL_CALL_END,
+          toolCallId: 'c1',
+          timestamp: now(),
+        }
+      }
+      yield {
+        type: EventType.RUN_FINISHED,
+        runId: 'r',
+        threadId: 't',
+        timestamp: now(),
+        metadata: {
+          tanstack: { finishReason: first ? 'tool_calls' : 'stop' },
+        },
+      }
+    })()
+  })
+  const toolNames = (index: number) =>
+    (calls[index]?.tools ?? []).map((entry) => entry.name)
+  return { adapter, calls, toolNames }
+}
+
+/** The sign-in URL of a `harness.auth_required` event, or `undefined`. */
+export function authorizationUrlOf(event: StreamChunk) {
+  if (
+    event.type !== EventType.CUSTOM ||
+    event.name !== HARNESS_EVENTS.authRequired
+  )
+    return undefined
+  const value: unknown = event.value
+  if (typeof value !== 'object' || value === null || !('url' in value))
+    return undefined
+  return typeof value.url === 'string' ? new URL(value.url) : undefined
+}
+
+/**
+ * Act as the user's browser for `/connect`: approve each sign-in the session
+ * asks for by calling its loopback redirect with `code` and the same `state`.
+ */
+export function approveSignIns(
+  session: HarnessSession,
+  code: string,
+  /** The `iss` the fake server sends back with the code (RFC 9207). */
+  iss?: string,
+) {
+  const authorizationUrls: Array<URL> = []
+  const controller = new AbortController()
+  void (async () => {
+    for await (const entry of session.events({ signal: controller.signal })) {
+      const authorizationUrl = authorizationUrlOf(entry.event)
+      if (!authorizationUrl) continue
+      authorizationUrls.push(authorizationUrl)
+      const redirect = new URL(
+        authorizationUrl.searchParams.get('redirect_uri') ?? '',
+      )
+      redirect.searchParams.set('code', code)
+      if (iss) redirect.searchParams.set('iss', iss)
+      redirect.searchParams.set(
+        'state',
+        authorizationUrl.searchParams.get('state') ?? '',
+      )
+      await fetch(redirect)
+    }
+  })()
+  return { authorizationUrls, stop: () => controller.abort() }
+}
+
+/**
+ * A spec 2026 server with one `book` tool. The first call asks for `input`.
+ * The retry records the answer in `answers` and ends the call.
+ */
+export function elicitServer(input: InputRequest) {
+  const answers: Array<unknown> = []
+  const handler = createMcpHandler(
+    () => {
+      const server = new McpServer({ name: 'trips', version: '1.0.0' })
+      server.registerTool(
+        'book',
+        {
+          description: 'Book a trip',
+          inputSchema: z.object({ text: z.string() }),
+        },
+        (_args, ctx) => {
+          const responses = ctx.mcpReq.inputResponses
+          if (responses === undefined) {
+            return inputRequired({ inputRequests: { trip: input } })
+          }
+          answers.push(responses.trip)
+          return { content: [{ type: 'text', text: 'booked' }] }
+        },
+      )
+      return server
+    },
+    { legacy: 'reject', keepAliveMs: 0 },
+  )
+  return { answers, fetch: (request: Request) => handler.fetch(request) }
+}
+
+/** The form the `book` tool of {@link elicitServer} asks for. */
+export const tripForm = {
+  message: 'Which city?',
+  requestedSchema: {
+    type: 'object' as const,
+    properties: { city: { type: 'string' as const } },
+    required: ['city'],
+  },
+}
+
+/**
+ * A spec 2025 server with one `book` tool. The tool sends each of `asks` to
+ * the client as an `elicitation/create` request, and records each answer in
+ * `answers`.
+ */
+export async function legacyElicitServer(
+  asks: Array<ElicitRequestFormParams | ElicitRequestURLParams>,
+) {
+  const answers: Array<unknown> = []
+  const server = new McpServer({ name: 'trips', version: '1.0.0' })
+  server.registerTool(
+    'book',
+    {
+      description: 'Book a trip',
+      inputSchema: z.object({ text: z.string() }),
+    },
+    async (_args, ctx) => {
+      for (const ask of asks) answers.push(await ctx.mcpReq.elicitInput(ask))
+      return { content: [{ type: 'text', text: 'booked' }] }
+    },
+  )
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: () => crypto.randomUUID(),
+  })
+  await server.connect(transport)
+  return {
+    answers,
+    fetch: (request: Request) => transport.handleRequest(request),
+  }
+}
+
+/**
+ * A spec 2026 server with one `book` tool that asks for each of `inputs` in
+ * turn, one round each. `requestState` carries the round. The retries record
+ * the answers in `answers`.
+ */
+export function roundsServer(inputs: Array<InputRequest>) {
+  const answers: Array<unknown> = []
+  const handler = createMcpHandler(
+    () => {
+      const server = new McpServer({ name: 'trips', version: '1.0.0' })
+      server.registerTool(
+        'book',
+        {
+          description: 'Book a trip',
+          inputSchema: z.object({ text: z.string() }),
+        },
+        (_args, ctx) => {
+          const state: unknown = ctx.mcpReq.requestState()
+          const round = typeof state === 'string' ? Number(state) : 0
+          const responses = ctx.mcpReq.inputResponses
+          if (responses !== undefined) answers.push(responses[`r${round - 1}`])
+          const input = inputs[round]
+          if (input === undefined) {
+            return { content: [{ type: 'text', text: 'booked' }] }
+          }
+          return inputRequired({
+            inputRequests: { [`r${round}`]: input },
+            requestState: String(round + 1),
+          })
+        },
+      )
+      return server
+    },
+    { legacy: 'reject', keepAliveMs: 0 },
+  )
+  return { answers, fetch: (request: Request) => handler.fetch(request) }
+}
diff --git a/packages/ai-mcp/tests/connector.test.ts b/packages/ai-mcp/tests/connector.test.ts
new file mode 100644
index 0000000000..603ff00bec
--- /dev/null
+++ b/packages/ai-mcp/tests/connector.test.ts
@@ -0,0 +1,405 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { inputRequired } from '@modelcontextprotocol/server'
+import { EventType } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { mcpConnector } from '../src/connector'
+import {
+  approveSignIns,
+  elicitServer,
+  legacyElicitServer,
+  mockTextAdapter,
+  recorder,
+  tripForm,
+} from './connector-helpers'
+import { startProtectedServer } from './protected-server'
+import type { StreamChunk } from '@tanstack/ai'
+
+/** A model that calls `tool` once, then answers with the tool result it saw. */
+function modelCalling(tool: string, args: { text: string }) {
+  let call = 0
+  const now = () => Date.now()
+  return mockTextAdapter((options) =>
+    (async function* (): AsyncGenerator<StreamChunk> {
+      call += 1
+      yield {
+        type: EventType.RUN_STARTED,
+        runId: 'r',
+        threadId: 't',
+        timestamp: now(),
+      }
+      if (call === 1) {
+        yield {
+          type: EventType.TOOL_CALL_START,
+          toolCallId: 'c1',
+          toolCallName: tool,
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.TOOL_CALL_ARGS,
+          toolCallId: 'c1',
+          delta: JSON.stringify(args),
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.TOOL_CALL_END,
+          toolCallId: 'c1',
+          timestamp: now(),
+        }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId: 'r',
+          threadId: 't',
+          timestamp: now(),
+          metadata: { tanstack: { finishReason: 'tool_calls' } },
+        }
+        return
+      }
+      const last = options.messages.at(-1)
+      const text = `saw: ${typeof last?.content === 'string' ? last.content : JSON.stringify(last?.content)}`
+      yield {
+        type: EventType.TEXT_MESSAGE_START,
+        messageId: `m${call}`,
+        role: 'assistant',
+        timestamp: now(),
+      }
+      yield {
+        type: EventType.TEXT_MESSAGE_CONTENT,
+        messageId: `m${call}`,
+        delta: text,
+        timestamp: now(),
+      }
+      yield {
+        type: EventType.TEXT_MESSAGE_END,
+        messageId: `m${call}`,
+        timestamp: now(),
+      }
+      yield {
+        type: EventType.RUN_FINISHED,
+        runId: 'r',
+        threadId: 't',
+        timestamp: now(),
+        metadata: { tanstack: { finishReason: 'stop' } },
+      }
+    })(),
+  )
+}
+
+const cleanups: Array<() => unknown> = []
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0).reverse()) await cleanup()
+})
+
+describe('mcpConnector', () => {
+  it('signs in with OAuth discovery, registration, and PKCE, then gives the model the server tools', async () => {
+    const protectedServer = await startProtectedServer()
+    cleanups.push(() => protectedServer.close())
+    const persistence = memoryPersistence()
+    const host = createHarnessHost({ persistence })
+    cleanups.push(() => host.close())
+    const harness = defineHarness({
+      name: 'test/mcp-connector',
+      adapter: modelCalling('demo_echo', { text: 'hello' }),
+      plugins: () => [
+        mcpConnector({ id: 'demo', label: 'Demo', url: protectedServer.url }),
+      ],
+    })
+    const session = await host.open(harness, {
+      threadId: 't',
+      principal: { id: 'user-1' },
+    })
+    const browser = approveSignIns(session, 'code-1')
+    cleanups.push(browser.stop)
+
+    await expect(session.command('connect:demo')).resolves.toBe(
+      'Connected to Demo.',
+    )
+    const authorizationUrl = browser.authorizationUrls.at(-1)
+    expect(authorizationUrl?.searchParams.get('client_id')).toBe('client-1')
+    expect(authorizationUrl?.searchParams.get('code_challenge_method')).toBe(
+      'S256',
+    )
+    expect(
+      new URL(authorizationUrl?.searchParams.get('redirect_uri') ?? '')
+        .hostname,
+    ).toBe('127.0.0.1')
+    // No `scopes` option: the sign-in asks for no scope.
+    expect(authorizationUrl?.searchParams.has('scope')).toBe(false)
+    expect(protectedServer.seen.registrations).toHaveLength(1)
+    expect(protectedServer.seen.registrations[0]).toMatchObject({
+      client_name: 'TanStack AI Harness',
+    })
+    expect(protectedServer.seen.registrations[0]).not.toHaveProperty('scope')
+    expect(
+      protectedServer.seen.tokenRequests[0]?.get('code_verifier'),
+    ).toBeTruthy()
+
+    const saved = await persistence.stores.credentials.get({
+      scope: { threadId: 't', userId: 'user-1' },
+      id: 'demo',
+    })
+    expect(saved).toMatchObject({
+      type: 'oauth',
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+      client: { clientId: 'client-1' },
+    })
+
+    // The echo tool is read-only, so the default rule runs it without approval.
+    const turn = await session.prompt('echo hello')
+    expect(turn.text).toContain('echo: hello')
+    // The model never sees the token.
+    expect(
+      JSON.stringify(await persistence.stores.messages.loadThread('t')),
+    ).not.toContain('access-1')
+
+    await session.command('disconnect:demo')
+    expect(
+      await persistence.stores.credentials.get({
+        scope: { threadId: 't', userId: 'user-1' },
+        id: 'demo',
+      }),
+    ).toBeNull()
+  })
+
+  it('keeps one sign-in per sender in a shared thread', async () => {
+    const protectedServer = await startProtectedServer()
+    cleanups.push(() => protectedServer.close())
+    const model = recorder()
+    const persistence = memoryPersistence()
+    const host = createHarnessHost({ persistence })
+    cleanups.push(() => host.close())
+    const alice = { id: 'alice' }
+    const bob = { id: 'bob' }
+    const session = await host.open(
+      defineHarness({
+        name: 'test/mcp-connector-shared',
+        adapter: model.adapter,
+        plugins: () => [
+          mcpConnector({ id: 'demo', label: 'Demo', url: protectedServer.url }),
+        ],
+      }),
+      { threadId: 't', principal: alice },
+    )
+    const browser = approveSignIns(session, 'code-1')
+    cleanups.push(browser.stop)
+    const savedFor = (userId: string) =>
+      persistence.stores.credentials.get({
+        scope: { threadId: 't', userId },
+        id: 'demo',
+      })
+
+    await session.command('connect:demo', undefined, { principal: bob })
+    expect(await savedFor('bob')).not.toBeNull()
+    expect(await savedFor('alice')).toBeNull()
+
+    await session.prompt('hi', { principal: bob })
+    await session.prompt('hi', { principal: alice })
+    await session.prompt('hi', { principal: bob })
+    // Only bob signed in, so only his turns get the server tools.
+    expect(model.toolNames(0)).toEqual(['demo_echo'])
+    expect(model.toolNames(1)).toEqual([])
+    expect(JSON.stringify(model.calls[1]?.systemPrompts)).toContain(
+      'run /connect demo',
+    )
+    expect(model.toolNames(2)).toEqual(['demo_echo'])
+
+    // Alice signs in for her own turns.
+    await session.command('connect:demo', undefined, { principal: alice })
+    await session.prompt('hi', { principal: alice })
+    expect(await savedFor('alice')).not.toBeNull()
+    expect(model.toolNames(3)).toEqual(['demo_echo'])
+  })
+
+  it('keeps colliding sender names separate in one shared thread', async () => {
+    const protectedServer = await startProtectedServer()
+    cleanups.push(() => protectedServer.close())
+    const first = { tenantId: 'a', id: 'b:c' }
+    const second = { tenantId: 'a:b', id: 'c' }
+    const persistence = memoryPersistence()
+    for (const [principal, accessToken] of [
+      [first, 'first-token'],
+      [second, 'second-token'],
+    ] as const) {
+      await persistence.stores.credentials.set({
+        scope: {
+          threadId: 't',
+          tenantId: principal.tenantId,
+          userId: principal.id,
+        },
+        id: 'demo',
+        credential: {
+          type: 'oauth',
+          accessToken,
+          client: {
+            clientId: 'client-1',
+            redirectUri: 'http://127.0.0.1/callback',
+            issuer: protectedServer.issuer,
+          },
+        },
+      })
+    }
+    const initialized: Array<string> = []
+    const toolLists: Array<string> = []
+    const fetchForSender: typeof fetch = async (input, init) => {
+      const request = new Request(input, init)
+      const token = request.headers
+        .get('authorization')
+        ?.replace(/^Bearer /, '')
+      const raw = request.method === 'POST' ? await request.clone().text() : ''
+      const body: unknown = raw ? JSON.parse(raw) : undefined
+      const method =
+        typeof body === 'object' && body !== null && 'method' in body
+          ? body.method
+          : undefined
+      if (method === 'initialize') initialized.push(token ?? '')
+      if (method === 'tools/list') toolLists.push(token ?? '')
+      if (token) request.headers.set('authorization', 'Bearer access-1')
+      const response = await fetch(request)
+      if (method !== 'tools/list' || !response.ok) return response
+      const result: unknown = await response.json()
+      if (
+        typeof result !== 'object' ||
+        result === null ||
+        !('result' in result) ||
+        typeof result.result !== 'object' ||
+        result.result === null ||
+        !('tools' in result.result) ||
+        !Array.isArray(result.result.tools)
+      ) {
+        throw new Error('The MCP server did not return tools.')
+      }
+      for (const tool of result.result.tools) {
+        if (typeof tool !== 'object' || tool === null || !('name' in tool)) {
+          throw new Error('The MCP server returned an invalid tool.')
+        }
+        tool.name = token === 'first-token' ? 'first_echo' : 'second_echo'
+      }
+      return new Response(JSON.stringify(result), {
+        status: response.status,
+        headers: response.headers,
+      })
+    }
+    const model = recorder()
+    const host = createHarnessHost({ persistence })
+    cleanups.push(() => host.close())
+    const session = await host.open(
+      defineHarness({
+        name: 'test/mcp-connector-colliding-senders',
+        adapter: model.adapter,
+        plugins: () => [
+          mcpConnector({
+            id: 'demo',
+            label: 'Demo',
+            url: protectedServer.url,
+            fetch: fetchForSender,
+          }),
+        ],
+      }),
+      { threadId: 't', principal: first },
+    )
+    await session.prompt('first', { principal: first })
+    await session.prompt('second', { principal: second })
+    await session.prompt('first again', { principal: first })
+    expect(model.toolNames(0)).toEqual(['demo_first_echo'])
+    expect(model.toolNames(1)).toEqual(['demo_second_echo'])
+    expect(model.toolNames(2)).toEqual(['demo_first_echo'])
+    expect(initialized).toEqual(['first-token', 'second-token'])
+    // tools() walks tools/list two times on a spec 2025 server: a raw walk,
+    // then listTools() for the SDK's output checks. Each walk of a sender
+    // uses that sender's token.
+    expect(toolLists).toEqual([
+      'first-token',
+      'first-token',
+      'second-token',
+      'second-token',
+    ])
+  })
+
+  it('tells the model to ask for /connect before sign-in', async () => {
+    const model = recorder()
+    const host = createHarnessHost({ persistence: memoryPersistence() })
+    cleanups.push(() => host.close())
+    const session = await host.open(
+      defineHarness({
+        name: 'test/mcp-connector-off',
+        adapter: model.adapter,
+        plugins: () => [
+          mcpConnector({
+            id: 'demo',
+            label: 'Demo',
+            url: 'http://127.0.0.1:9/mcp',
+          }),
+        ],
+      }),
+      { threadId: 't' },
+    )
+    await session.prompt('hi')
+    expect(JSON.stringify(model.calls[0]?.systemPrompts)).toContain(
+      'run /connect demo',
+    )
+    expect(model.toolNames(0)).toEqual([])
+    expect(session.commands().map((command) => command.name)).toEqual([
+      'connect:demo',
+      'disconnect:demo',
+    ])
+  })
+
+  it.each([
+    ['spec 2026', async () => elicitServer(inputRequired.elicit(tripForm))],
+    [
+      'spec 2025',
+      async () => legacyElicitServer([{ mode: 'form', ...tripForm }]),
+    ],
+  ])(
+    'asks a form elicitation of a %s server as a session question and sends the answer',
+    async (_name, start) => {
+      const trips = await start()
+      const persistence = memoryPersistence()
+      // A saved sign-in, so the test skips the OAuth steps.
+      await persistence.stores.credentials.set({
+        scope: { threadId: 't', userId: 'user-1' },
+        id: 'trips',
+        credential: { type: 'oauth', accessToken: 'access-1' },
+      })
+      const model = recorder('trips_book')
+      const host = createHarnessHost({ persistence })
+      cleanups.push(() => host.close())
+      const session = await host.open(
+        defineHarness({
+          name: 'test/mcp-connector-elicit',
+          adapter: model.adapter,
+          plugins: () => [
+            mcpConnector({
+              id: 'trips',
+              label: 'Trips',
+              url: 'http://mcp.test/mcp',
+              needsApproval: () => false,
+              fetch: async (input, init) =>
+                trips.fetch(new Request(input, init)),
+            }),
+          ],
+        }),
+        { threadId: 't', principal: { id: 'user-1' } },
+      )
+      const turn = session.prompt('book a trip')
+      await vi.waitFor(() =>
+        expect(session.snapshot().pendingQuestions).toHaveLength(1),
+      )
+      const [question] = session.snapshot().pendingQuestions
+
+      expect(question).toMatchObject({
+        message: 'Which city?',
+        schema: tripForm.requestedSchema,
+      })
+      await session.answer({
+        questionId: question?.questionId ?? '',
+        value: { city: 'Rome' },
+      })
+      await turn
+      expect(trips.answers).toEqual([
+        { action: 'accept', content: { city: 'Rome' } },
+      ])
+    },
+  )
+})
diff --git a/packages/ai-mcp/tests/harness-media.test.ts b/packages/ai-mcp/tests/harness-media.test.ts
new file mode 100644
index 0000000000..4212406253
--- /dev/null
+++ b/packages/ai-mcp/tests/harness-media.test.ts
@@ -0,0 +1,479 @@
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, sep } from 'node:path'
+import {
+  Client,
+  StreamableHTTPClientTransport,
+} from '@modelcontextprotocol/client'
+import { EventType, defineAgent } from '@tanstack/ai'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { createHarnessMcpServer } from '../src/harness'
+import type {
+  AnyTextAdapter,
+  ImageAdapter,
+  ModelMessage,
+  StreamChunk,
+} from '@tanstack/ai'
+import type { AnyHarness } from '@tanstack/ai-harness'
+import type { HarnessMcpServerOptions } from '../src/harness'
+
+const serverUrl = new URL('https://harness.example.com/mcp')
+const now = () => Date.now()
+/** The bytes "hello", and their base64. */
+const hello = new TextEncoder().encode('hello')
+const helloBase64 = 'aGVsbG8='
+/** One byte over the 5 MB inline limit. */
+const bigImage = new Uint8Array(5 * 1024 * 1024 + 1)
+
+const mediaListShape = z.object({
+  media: z.array(z.object({ id: z.string(), uri: z.string() })),
+})
+const linkShape = z.object({ uri: z.string() })
+
+function textTurn(text: string): Array<StreamChunk> {
+  return [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+    },
+    {
+      type: EventType.TEXT_MESSAGE_START,
+      messageId: `m-${text}`,
+      role: 'assistant',
+      timestamp: now(),
+    },
+    {
+      type: EventType.TEXT_MESSAGE_CONTENT,
+      messageId: `m-${text}`,
+      delta: text,
+      timestamp: now(),
+    },
+    {
+      type: EventType.TEXT_MESSAGE_END,
+      messageId: `m-${text}`,
+      timestamp: now(),
+    },
+    {
+      type: EventType.RUN_FINISHED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+      metadata: { tanstack: { finishReason: 'stop' } },
+    },
+  ]
+}
+
+/** One model call that calls the tool `name` with no input. */
+function toolCallTurn(name: string): Array<StreamChunk> {
+  return [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+    },
+    {
+      type: EventType.TOOL_CALL_START,
+      toolCallId: 'call-0',
+      toolCallName: name,
+      timestamp: now(),
+    },
+    {
+      type: EventType.TOOL_CALL_ARGS,
+      toolCallId: 'call-0',
+      delta: '{}',
+      timestamp: now(),
+    },
+    { type: EventType.TOOL_CALL_END, toolCallId: 'call-0', timestamp: now() },
+    {
+      type: EventType.RUN_FINISHED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+      metadata: { tanstack: { finishReason: 'tool_calls' } },
+    },
+  ]
+}
+
+/** A model that plays `turns` in order and keeps the messages of each call. */
+function scripted(turns: Array<Array<StreamChunk>> = []) {
+  const calls: Array<Array<ModelMessage>> = []
+  const adapter: AnyTextAdapter = {
+    kind: 'text',
+    name: 'mock',
+    model: 'mock',
+    // `~types` holds types only. Its values are never read, so they are casts.
+    '~types': {
+      providerOptions: {} as Record<string, unknown>,
+      inputModalities: ['text'] as readonly ['text'],
+      messageMetadataByModality: {
+        text: undefined as unknown,
+        image: undefined as unknown,
+        audio: undefined as unknown,
+        video: undefined as unknown,
+        document: undefined as unknown,
+      },
+      toolCapabilities: [] as ReadonlyArray<string>,
+      toolCallMetadata: undefined as unknown,
+      systemPromptMetadata: undefined as never,
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+    chatStream: (options) => {
+      const turn = turns[calls.length] ?? textTurn('ok')
+      calls.push(options.messages)
+      return (async function* () {
+        yield* turn
+      })()
+    },
+  }
+  return { adapter, calls }
+}
+
+/** An image model that returns `bytes` as one image. */
+function imageModel(bytes: Uint8Array): ImageAdapter<string> {
+  return {
+    kind: 'image',
+    name: 'fake-image',
+    model: 'fake-image-model',
+    '~types': {
+      providerOptions: {},
+      modelProviderOptionsByName: {},
+      modelSizeByName: {},
+      modelInputModalitiesByName: {},
+    },
+    generateImages: async () => ({
+      id: 'image-1',
+      model: 'fake-image-model',
+      images: [{ b64Json: Buffer.from(bytes).toString('base64') }],
+    }),
+  }
+}
+
+/** An agent that paints one image with `bytes`. */
+function painter(bytes: Uint8Array) {
+  return defineAgent({
+    name: 'painter',
+    description: 'Paints',
+    run: async (ctx) => {
+      await ctx.generateImage({ adapter: imageModel(bytes), prompt: 'a cat' })
+      return 'painted'
+    },
+  })
+}
+
+const cleanups: Array<() => Promise<unknown>> = []
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0).reverse()) await cleanup()
+})
+
+type ServerOptions = Omit<HarnessMcpServerOptions, 'host' | 'harness'>
+
+/** A real MCP client (spec 2026) on a harness MCP server. */
+async function serve(harness: AnyHarness, options: ServerOptions = {}) {
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  cleanups.push(() => host.close())
+  const server = await createHarnessMcpServer({ host, harness, ...options })
+  const client = new Client(
+    { name: 'tester', version: '1.0.0' },
+    { versionNegotiation: { mode: { pin: '2026-07-28' } } },
+  )
+  const transport = new StreamableHTTPClientTransport(serverUrl, {
+    fetch: async (input, init) => server.fetch(new Request(input, init)),
+  })
+  await client.connect(transport)
+  cleanups.push(() => client.close())
+  return client
+}
+
+/** A chat harness on an MCP server. `calls` has the messages of each model call. */
+async function chatServer(options: ServerOptions = {}) {
+  const model = scripted()
+  const harness = defineHarness({
+    name: 'test/mcp-media',
+    adapter: model.adapter,
+  })
+  const client = await serve(harness, options)
+  return { client, calls: model.calls }
+}
+
+function chat(client: Client, args: Record<string, unknown>) {
+  return client.callTool({ name: 'chat', arguments: args })
+}
+
+/** The content of the last user message that a model call got. */
+function userContent(messages: Array<ModelMessage> | undefined) {
+  return messages?.findLast((message) => message.role === 'user')?.content
+}
+
+/** The MCP result of a tool call that threw an error with `message`. */
+function toolError(message: string) {
+  return { isError: true, content: [{ type: 'text', text: message }] }
+}
+
+/** The model content for the question "What is this?" with the image "hello". */
+const helloImageQuestion = [
+  { type: 'text', content: 'What is this?' },
+  {
+    type: 'image',
+    source: { type: 'data', value: helloBase64, mimeType: 'image/png' },
+  },
+]
+
+/**
+ * A temp folder with `allowed/cat.png` ("hello"), `allowed/notes.xyz`, and
+ * `outside/secret.png`.
+ */
+async function folders() {
+  const root = await mkdtemp(join(tmpdir(), 'harness-mcp-media-'))
+  cleanups.push(() => rm(root, { recursive: true, force: true }))
+  const allowed = join(root, 'allowed')
+  const outside = join(root, 'outside')
+  await mkdir(allowed)
+  await mkdir(outside)
+  await writeFile(join(allowed, 'cat.png'), hello)
+  await writeFile(join(allowed, 'notes.xyz'), 'notes')
+  await writeFile(join(outside, 'secret.png'), 'secret')
+  return { allowed, outside }
+}
+
+const outsideRefusal = (path: string) =>
+  `Cannot read ${path}. It must be a file inside the folders this server may read.`
+
+describe('chat attachments', () => {
+  it('sends a data attachment to the model', async () => {
+    const { client, calls } = await chatServer()
+
+    await chat(client, {
+      message: 'What is this?',
+      attachments: [
+        { data: helloBase64, mimeType: 'image/png', name: 'cat.png' },
+      ],
+    })
+
+    expect(userContent(calls[0])).toEqual(helloImageQuestion)
+  })
+
+  it('sends a path attachment inside filePaths to the model', async () => {
+    const { allowed } = await folders()
+    const { client, calls } = await chatServer({ filePaths: [allowed] })
+
+    await chat(client, {
+      message: 'What is this?',
+      attachments: [{ path: join(allowed, 'cat.png') }],
+    })
+
+    expect(userContent(calls[0])).toEqual(helloImageQuestion)
+  })
+
+  it.each([
+    {
+      given: "a '..' path out of filePaths",
+      filePaths: true,
+      // Not `join`: it would remove the '..'.
+      path: (allowed: string) =>
+        `${allowed}${sep}..${sep}outside${sep}secret.png`,
+      refusal: outsideRefusal,
+    },
+    {
+      given: 'a path when the server has no filePaths',
+      filePaths: false,
+      path: (allowed: string) => join(allowed, 'cat.png'),
+      refusal: () =>
+        'This server does not read files. Send the file as data or url.',
+    },
+    {
+      given: 'a file type it does not know',
+      filePaths: true,
+      path: (allowed: string) => join(allowed, 'notes.xyz'),
+      refusal: () =>
+        'Unknown file type: notes.xyz. Send the file as data with its mimeType.',
+    },
+  ])('refuses $given', async ({ filePaths, path, refusal }) => {
+    const { allowed } = await folders()
+    const { client, calls } = await chatServer(
+      filePaths ? { filePaths: [allowed] } : {},
+    )
+
+    const reply = await chat(client, {
+      message: 'Read this',
+      attachments: [{ path: path(allowed) }],
+    })
+
+    expect(reply).toMatchObject(toolError(refusal(path(allowed))))
+    expect(calls).toEqual([])
+  })
+
+  it('refuses a path through a symlink out of filePaths', async (ctx) => {
+    const { allowed, outside } = await folders()
+    // A junction needs no admin rights on Windows. Other systems make a
+    // normal symlink to the folder.
+    const linked = await symlink(outside, join(allowed, 'link'), 'junction')
+      .then(() => true)
+      .catch(() => false)
+    ctx.skip(!linked, 'This system cannot make a symlink.')
+    const { client, calls } = await chatServer({ filePaths: [allowed] })
+    const path = join(allowed, 'link', 'secret.png')
+
+    const reply = await chat(client, {
+      message: 'Read this',
+      attachments: [{ path }],
+    })
+
+    expect(reply).toMatchObject(toolError(outsideRefusal(path)))
+    expect(calls).toEqual([])
+  })
+
+  it('passes a url attachment to the model and does not fetch it', async () => {
+    // A fetch fails, so the test never reaches the network.
+    const fetchSpy = vi
+      .spyOn(globalThis, 'fetch')
+      .mockRejectedValue(new Error('No network in this test.'))
+    cleanups.push(async () => fetchSpy.mockRestore())
+    const { client, calls } = await chatServer()
+
+    await chat(client, {
+      message: 'Look',
+      attachments: [{ url: 'https://cdn.example.com/cat.png' }],
+    })
+
+    expect(userContent(calls[0])).toEqual([
+      { type: 'text', content: 'Look' },
+      {
+        type: 'image',
+        source: {
+          type: 'url',
+          value: 'https://cdn.example.com/cat.png',
+          mimeType: 'image/png',
+        },
+      },
+    ])
+    expect(fetchSpy).not.toHaveBeenCalled()
+  })
+
+  it('refuses a url when neither mimeType nor the path gives a kind', async () => {
+    const { client, calls } = await chatServer()
+
+    const reply = await chat(client, {
+      message: 'Look',
+      attachments: [{ url: 'https://example.com/download' }],
+    })
+
+    expect(reply).toMatchObject(
+      toolError(
+        'Cannot tell the kind of https://example.com/download. Add its mimeType.',
+      ),
+    )
+    expect(calls).toEqual([])
+  })
+
+  it('returns the refusal of the media store as a tool error', async () => {
+    const { client, calls } = await chatServer()
+
+    const reply = await chat(client, {
+      message: 'Open this',
+      attachments: [{ data: helloBase64, mimeType: 'application/zip' }],
+    })
+
+    expect(reply).toMatchObject(
+      toolError('Files of type application/zip are not supported.'),
+    )
+    expect(calls).toEqual([])
+  })
+})
+
+describe('media in results', () => {
+  it('chat returns a small image of the turn inline and lists it', async () => {
+    const lead = scripted([toolCallTurn('painter'), textTurn('Here it is.')])
+    const client = await serve(
+      defineHarness({
+        name: 'test/mcp-media',
+        adapter: lead.adapter,
+        subagents: { agents: [painter(hello)] },
+      }),
+    )
+
+    const reply = await chat(client, { message: 'Paint a cat' })
+
+    expect(reply.structuredContent).toEqual({
+      status: 'completed',
+      text: 'Here it is.',
+      interrupts: [],
+      questions: [],
+      media: [
+        {
+          id: expect.any(String),
+          kind: 'image',
+          name: expect.any(String),
+          mimeType: 'image/png',
+          size: 5,
+          uri: expect.any(String),
+        },
+      ],
+    })
+    const [media] = mediaListShape.parse(reply.structuredContent).media
+    expect(media?.uri).toBe(`harness-media://main/${media?.id}`)
+    expect(reply.content).toEqual([
+      { type: 'text', text: JSON.stringify(reply.structuredContent) },
+      { type: 'image', data: helloBase64, mimeType: 'image/png' },
+    ])
+  })
+
+  /** Runs `agent_painter` with an image over 5 MB. `uri` is its media link. */
+  async function paintBig() {
+    const client = await serve(
+      defineHarness({
+        name: 'test/mcp-media',
+        adapter: scripted().adapter,
+        agents: [painter(bigImage)],
+        expose: { agents: ['painter'] },
+      }),
+    )
+    const reply = await client.callTool({
+      name: 'agent_painter',
+      arguments: {},
+    })
+    const link = z.array(z.unknown()).parse(reply.content)[1]
+    return { client, reply, uri: linkShape.parse(link).uri }
+  }
+
+  it('returns an image over 5 MB as a resource link', async () => {
+    const { reply } = await paintBig()
+
+    expect(reply.content).toEqual([
+      { type: 'text', text: 'painted' },
+      {
+        type: 'resource_link',
+        uri: expect.stringMatching(/^harness-media:\/\/main\/[^/]+$/),
+        name: expect.any(String),
+        mimeType: 'image/png',
+      },
+    ])
+  })
+
+  it('reads the bytes of a media link with resources/read', async () => {
+    const { client, uri } = await paintBig()
+
+    const read = await client.readResource({ uri })
+
+    const [contents] = read.contents
+    expect(contents).toMatchObject({ uri, mimeType: 'image/png' })
+    const blob = z.object({ blob: z.string() }).parse(contents).blob
+    expect(Buffer.from(blob, 'base64').equals(Buffer.from(bigImage))).toBe(true)
+  })
+
+  it('refuses to read a media link with the thread of another conversation', async () => {
+    const { client, uri } = await paintBig()
+    const id = uri.slice('harness-media://main/'.length)
+
+    const read = client.readResource({ uri: `harness-media://other/${id}` })
+
+    await expect(read).rejects.toThrow(
+      `Media ${id} was not found in thread other.`,
+    )
+  })
+})
diff --git a/packages/ai-mcp/tests/harness-plugin.test.ts b/packages/ai-mcp/tests/harness-plugin.test.ts
new file mode 100644
index 0000000000..36d18793e0
--- /dev/null
+++ b/packages/ai-mcp/tests/harness-plugin.test.ts
@@ -0,0 +1,434 @@
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { McpServer, inputRequired } from '@modelcontextprotocol/server'
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio'
+import { toolDefinition } from '@tanstack/ai'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
+import { mcp } from '../src/harness'
+import { createMCPServer } from '../src/server/index'
+import {
+  approveSignIns,
+  elicitServer,
+  legacyElicitServer,
+  recorder,
+  roundsServer,
+  tripForm,
+} from './connector-helpers'
+import { startProtectedServer } from './protected-server'
+import type { McpServerConfig } from '../src/harness'
+
+// With this env var, this file is the stdio server of the stdio test.
+const childEnv = 'TANSTACK_AI_MCP_PLUGIN_CHILD'
+
+const cleanups: Array<() => unknown> = []
+
+/** A server with one `echo` tool, in this process. */
+function echoServer() {
+  const echo = toolDefinition({
+    name: 'echo',
+    description: 'Echo text',
+    inputSchema: z.object({ text: z.string() }),
+  }).server(async ({ text }) => text)
+  return createMCPServer({ name: 'echo', version: '1.0.0', tools: [echo] })
+}
+
+/** An `http` server config whose requests go to `handle`, with no network. */
+function httpServer(
+  handle: (request: Request) => Promise<Response>,
+  options: Pick<McpServerConfig, 'timeoutMs' | 'codeMode'> = {},
+) {
+  const config: McpServerConfig = {
+    type: 'http',
+    url: 'http://mcp.test/mcp',
+    fetch: async (input, init) => handle(new Request(input, init)),
+    ...options,
+  }
+  return config
+}
+
+/** Opens a session with `mcp({ servers })` and the recording `model`. */
+async function openWith(
+  servers: Record<string, McpServerConfig>,
+  model = recorder(),
+) {
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  cleanups.push(() => host.close())
+  const harness = defineHarness({
+    name: 'test/mcp-plugin',
+    adapter: model.adapter,
+    plugins: () => [mcp({ servers })],
+  })
+  const session = await host.open(harness, {
+    threadId: 't',
+    principal: { id: 'user-1' },
+  })
+  return { host, session, model }
+}
+
+function isRunning(pid: number) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+if (process.env[childEnv] === '1') {
+  // An SDK server, like most published stdio servers.
+  const server = new McpServer({ name: 'local', version: '1.0.0' })
+  server.registerTool(
+    'pid',
+    {
+      description: 'Name the process of this server',
+      inputSchema: z.object({ text: z.string() }),
+    },
+    async () => ({
+      content: [{ type: 'text' as const, text: `pid:${process.pid}` }],
+    }),
+  )
+  await server.connect(new StdioServerTransport())
+} else {
+  afterEach(async () => {
+    for (const cleanup of cleanups.splice(0).reverse()) await cleanup()
+  })
+
+  describe('mcp', () => {
+    it('connects each server on its own, so a failed server leaves the tools of the others', async () => {
+      const good = echoServer()
+      const { session, model } = await openWith({
+        good: httpServer((request) => good.fetch(request)),
+        bad: httpServer(async () => {
+          throw new TypeError('connection refused')
+        }),
+      })
+      await session.prompt('hi')
+
+      expect(model.toolNames(0)).toEqual(['good_echo'])
+      const error =
+        'Failed to connect to MCP server: Version negotiation probe failed: connection refused'
+      await expect(session.command('mcp')).resolves.toBe(
+        `good: connected (1 tool)\nbad: failed: ${error}`,
+      )
+      expect(session.snapshot().plugins['tanstack/mcp']).toEqual({
+        servers: [
+          { name: 'good', status: 'connected', toolCount: 1 },
+          { name: 'bad', status: 'failed', error, toolCount: 0 },
+        ],
+      })
+    })
+
+    it('stops a server that does not answer within its timeoutMs', async () => {
+      const slow = echoServer()
+      const { session, model } = await openWith({
+        slow: httpServer(
+          async (request) => {
+            const body =
+              request.method === 'POST' ? await request.clone().text() : ''
+            // The tool list never comes, so only the timeout ends the wait.
+            if (body.includes('"tools/list"')) {
+              return new Promise<Response>(() => {})
+            }
+            return slow.fetch(request)
+          },
+          { timeoutMs: 100 },
+        ),
+      })
+      await session.prompt('hi')
+
+      expect(model.toolNames(0)).toEqual([])
+      await expect(session.command('mcp')).resolves.toMatch(
+        /^slow: failed: .*timed out/i,
+      )
+    })
+
+    it('stops a server that does not connect within its timeoutMs, and closes its request', async () => {
+      const good = echoServer()
+      const signals: Array<AbortSignal> = []
+      const { session, model } = await openWith({
+        good: httpServer((request) => good.fetch(request)),
+        silent: {
+          type: 'http',
+          url: 'http://mcp.test/mcp',
+          timeoutMs: 100,
+          // The handshake never gets an answer, so only the timeout ends the
+          // wait. The signal shows if the request was closed.
+          fetch: (_input, init) => {
+            if (init?.signal) signals.push(init.signal)
+            return new Promise<Response>(() => {})
+          },
+        },
+      })
+      await session.prompt('hi')
+
+      expect(model.toolNames(0)).toEqual(['good_echo'])
+      await expect(session.command('mcp')).resolves.toBe(
+        'good: connected (1 tool)\nsilent: failed: Failed to connect to MCP server: Version negotiation probe timed out after 100ms',
+      )
+      expect(signals.length).toBeGreaterThan(0)
+      expect(signals.every((signal) => signal.aborted)).toBe(true)
+    })
+
+    it('marks the tools of a codeMode server for code mode', async () => {
+      const plain = echoServer()
+      const coded = echoServer()
+      const { session, model } = await openWith({
+        plain: httpServer((request) => plain.fetch(request)),
+        coded: httpServer((request) => coded.fetch(request), {
+          codeMode: true,
+        }),
+      })
+      await session.prompt('hi')
+
+      const marks = (model.calls[0]?.tools ?? []).map((tool) => [
+        tool.name,
+        tool.metadata?.codeMode,
+      ])
+      expect(marks).toEqual([
+        ['plain_echo', undefined],
+        ['coded_echo', true],
+      ])
+    })
+
+    it.each([
+      [
+        'accepts',
+        { city: 'Paris' },
+        { action: 'accept', content: { city: 'Paris' } },
+      ],
+      ['declines', { action: 'decline' }, { action: 'decline' }],
+      ['cancels', { action: 'cancel' }, { action: 'cancel' }],
+    ])(
+      'asks a form elicitation as a session question, and the user %s',
+      async (_name, value, expected) => {
+        const trips = elicitServer(inputRequired.elicit(tripForm))
+        const model = recorder('trips_book')
+        const { session } = await openWith(
+          { trips: httpServer((request) => trips.fetch(request)) },
+          model,
+        )
+        const turn = session.prompt('book a trip')
+        await vi.waitFor(() =>
+          expect(session.snapshot().pendingQuestions).toHaveLength(1),
+        )
+        const [question] = session.snapshot().pendingQuestions
+
+        expect(question?.message).toBe('Which city?')
+        expect(question?.schema).toMatchObject(tripForm.requestedSchema)
+        expect(question?.url).toBeUndefined()
+        await session.answer({ questionId: question?.questionId ?? '', value })
+        await turn
+        expect(trips.answers).toEqual([expected])
+        expect(JSON.stringify(model.calls[1]?.messages)).toContain('booked')
+      },
+    )
+
+    it('asks a url elicitation as a session question with the url', async () => {
+      const trips = elicitServer(
+        inputRequired.elicitUrl({
+          message: 'Pay for the trip, then come back.',
+          url: 'https://pay.example.com/trip',
+        }),
+      )
+      const { session } = await openWith(
+        { trips: httpServer((request) => trips.fetch(request)) },
+        recorder('trips_book'),
+      )
+      const turn = session.prompt('book a trip')
+      await vi.waitFor(() =>
+        expect(session.snapshot().pendingQuestions).toHaveLength(1),
+      )
+      const [question] = session.snapshot().pendingQuestions
+
+      expect(question).toMatchObject({
+        message: 'Pay for the trip, then come back.',
+        url: 'https://pay.example.com/trip',
+      })
+      await session.answer({
+        questionId: question?.questionId ?? '',
+        value: 'done',
+      })
+      await turn
+      expect(trips.answers).toEqual([{ action: 'accept' }])
+    })
+
+    it.each([
+      [
+        'accepts',
+        { city: 'Paris' },
+        { action: 'accept', content: { city: 'Paris' } },
+      ],
+      ['declines', { action: 'decline' }, { action: 'decline' }],
+      ['cancels', { action: 'cancel' }, { action: 'cancel' }],
+    ])(
+      'asks an elicitation/create form request of a spec 2025 server, and the user %s',
+      async (_name, value, expected) => {
+        const trips = await legacyElicitServer([{ mode: 'form', ...tripForm }])
+        const model = recorder('trips_book')
+        const { session } = await openWith(
+          { trips: httpServer((request) => trips.fetch(request)) },
+          model,
+        )
+        const turn = session.prompt('book a trip')
+        await vi.waitFor(() =>
+          expect(session.snapshot().pendingQuestions).toHaveLength(1),
+        )
+        const [question] = session.snapshot().pendingQuestions
+
+        expect(question?.message).toBe('Which city?')
+        expect(question?.schema).toMatchObject(tripForm.requestedSchema)
+        await session.answer({ questionId: question?.questionId ?? '', value })
+        await turn
+        expect(trips.answers).toEqual([expected])
+        expect(JSON.stringify(model.calls[1]?.messages)).toContain('booked')
+      },
+    )
+
+    it('asks an elicitation/create url request of a spec 2025 server', async () => {
+      const trips = await legacyElicitServer([
+        {
+          mode: 'url',
+          message: 'Pay for the trip, then come back.',
+          url: 'https://pay.example.com/trip',
+          elicitationId: 'pay-1',
+        },
+      ])
+      const { session } = await openWith(
+        { trips: httpServer((request) => trips.fetch(request)) },
+        recorder('trips_book'),
+      )
+      const turn = session.prompt('book a trip')
+      await vi.waitFor(() =>
+        expect(session.snapshot().pendingQuestions).toHaveLength(1),
+      )
+      const [question] = session.snapshot().pendingQuestions
+
+      expect(question).toMatchObject({
+        message: 'Pay for the trip, then come back.',
+        url: 'https://pay.example.com/trip',
+      })
+      await session.answer({
+        questionId: question?.questionId ?? '',
+        value: 'done',
+      })
+      await turn
+      expect(trips.answers).toEqual([{ action: 'accept' }])
+    })
+
+    it('asks two elicitations of one spec 2026 tool call in turn', async () => {
+      const seat = {
+        message: 'Which seat?',
+        requestedSchema: {
+          type: 'object' as const,
+          properties: { seat: { type: 'string' as const } },
+          required: ['seat'],
+        },
+      }
+      const trips = roundsServer([
+        inputRequired.elicit(tripForm),
+        inputRequired.elicit(seat),
+      ])
+      const model = recorder('trips_book')
+      const { session } = await openWith(
+        { trips: httpServer((request) => trips.fetch(request)) },
+        model,
+      )
+      const turn = session.prompt('book a trip')
+      for (const [message, value] of [
+        ['Which city?', { city: 'Paris' }],
+        ['Which seat?', { seat: '12A' }],
+      ] as const) {
+        await vi.waitFor(() =>
+          expect(session.snapshot().pendingQuestions[0]?.message).toBe(message),
+        )
+        const [question] = session.snapshot().pendingQuestions
+        await session.answer({ questionId: question?.questionId ?? '', value })
+      }
+      await turn
+      expect(trips.answers).toEqual([
+        { action: 'accept', content: { city: 'Paris' } },
+        { action: 'accept', content: { seat: '12A' } },
+      ])
+      expect(JSON.stringify(model.calls[1]?.messages)).toContain('booked')
+    })
+
+    it('fails the tool call after 5 elicitations in one call', async () => {
+      const trips = roundsServer(
+        Array.from({ length: 6 }, () => inputRequired.elicit(tripForm)),
+      )
+      const model = recorder('trips_book')
+      const { session } = await openWith(
+        { trips: httpServer((request) => trips.fetch(request)) },
+        model,
+      )
+      const turn = session.prompt('book a trip')
+      for (let round = 0; round < 5; round++) {
+        await vi.waitFor(() =>
+          expect(session.snapshot().pendingQuestions).toHaveLength(1),
+        )
+        const [question] = session.snapshot().pendingQuestions
+        await session.answer({
+          questionId: question?.questionId ?? '',
+          value: { city: 'Paris' },
+        })
+      }
+      await turn
+      expect(trips.answers).toHaveLength(5)
+      expect(JSON.stringify(model.calls[1]?.messages)).toContain(
+        'asked for input more than 5 times',
+      )
+    })
+
+    it('runs a stdio server as a child process and stops it when the session closes', async () => {
+      const model = recorder('local_pid')
+      const { host, session } = await openWith(
+        {
+          local: {
+            type: 'stdio',
+            command: process.execPath,
+            args: ['--import', 'jiti/register', fileURLToPath(import.meta.url)],
+            cwd: fileURLToPath(new URL('..', import.meta.url)),
+            env: { [childEnv]: '1' },
+          },
+        },
+        model,
+      )
+      await session.prompt('which process runs the server?')
+      const seen = JSON.stringify(model.calls[1]?.messages)
+      const pid = Number(/pid:(\d+)/.exec(seen)?.[1])
+      expect(isRunning(pid)).toBe(true)
+
+      await host.close()
+      await vi.waitFor(() => expect(isRunning(pid)).toBe(false), {
+        timeout: 10_000,
+      })
+    }, 120_000)
+
+    it('signs in to an oauth server with /connect, then gives its tools', async () => {
+      const protectedServer = await startProtectedServer()
+      cleanups.push(() => protectedServer.close())
+      const { session, model } = await openWith({
+        demo: { type: 'http', url: protectedServer.url, oauth: true },
+      })
+      await session.prompt('before')
+      await expect(session.command('mcp')).resolves.toBe(
+        'demo: failed: Not signed in. Run /connect demo.',
+      )
+
+      const browser = approveSignIns(session, 'code-1')
+      cleanups.push(browser.stop)
+      await expect(session.command('connect:demo')).resolves.toBe(
+        'Connected to demo.',
+      )
+      await session.prompt('after')
+
+      expect(model.toolNames(0)).toEqual([])
+      expect(model.toolNames(1)).toEqual(['demo_echo'])
+      await expect(session.command('mcp')).resolves.toBe(
+        'demo: connected (1 tool)',
+      )
+    })
+  })
+}
diff --git a/packages/ai-mcp/tests/harness.test.ts b/packages/ai-mcp/tests/harness.test.ts
new file mode 100644
index 0000000000..8c925d80e9
--- /dev/null
+++ b/packages/ai-mcp/tests/harness.test.ts
@@ -0,0 +1,1378 @@
+import {
+  Client,
+  StreamableHTTPClientTransport,
+} from '@modelcontextprotocol/client'
+import {
+  EventType,
+  defineAgent,
+  defineChatMiddleware,
+  defineInterrupt,
+  toolDefinition,
+} from '@tanstack/ai'
+import {
+  HARNESS_EVENTS,
+  createHarnessHost,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '@tanstack/ai-harness'
+import { memoryPersistence } from '@tanstack/ai-persistence'
+import { afterEach, describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { createHarnessMcpServer } from '../src/harness'
+import type {
+  AnyTextAdapter,
+  InterruptBoundaryPhase,
+  ModelMessage,
+  StreamChunk,
+} from '@tanstack/ai'
+import type { AnyHarness, HarnessSession } from '@tanstack/ai-harness'
+import type { HarnessMcpServerOptions } from '../src/harness'
+
+const serverUrl = new URL('https://harness.example.com/mcp')
+const now = () => Date.now()
+
+const pendingShape = z.object({
+  interrupts: z.array(z.object({ id: z.string() })),
+  questions: z.array(z.object({ id: z.string() })),
+})
+
+/** The response schema of an approval for `remove`, which takes `{ path }`. */
+const removeApprovalSchema = {
+  oneOf: [
+    {
+      type: 'object',
+      properties: {
+        approved: { const: true },
+        // zod writes the input schema, so extra keys stay allowed.
+        editedArgs: {
+          $schema: 'https://json-schema.org/draft/2020-12/schema',
+          type: 'object',
+          properties: { path: { type: 'string' } },
+          required: ['path'],
+        },
+      },
+      required: ['approved'],
+      additionalProperties: false,
+    },
+    {
+      type: 'object',
+      properties: { approved: { const: false } },
+      required: ['approved'],
+      additionalProperties: false,
+    },
+  ],
+}
+
+/** A generic interrupt that asks for a review note. */
+const review = defineInterrupt({
+  id: 'review-plan',
+  responseSchema: z.object({ note: z.string() }),
+})
+
+const reviewSchema = {
+  type: 'object',
+  properties: { note: { type: 'string' } },
+  required: ['note'],
+}
+
+const questionShape = z.object({ questionId: z.string() })
+
+const controlTools = [
+  'answer',
+  'approve',
+  'cancel',
+  'chat',
+  'reject',
+  'resolve',
+  'status',
+  'steer',
+]
+
+function textTurn(text: string): Array<StreamChunk> {
+  return [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+    },
+    {
+      type: EventType.TEXT_MESSAGE_START,
+      messageId: `m-${text}`,
+      role: 'assistant',
+      timestamp: now(),
+    },
+    {
+      type: EventType.TEXT_MESSAGE_CONTENT,
+      messageId: `m-${text}`,
+      delta: text,
+      timestamp: now(),
+    },
+    {
+      type: EventType.TEXT_MESSAGE_END,
+      messageId: `m-${text}`,
+      timestamp: now(),
+    },
+    {
+      type: EventType.RUN_FINISHED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+      metadata: { tanstack: { finishReason: 'stop' } },
+    },
+  ]
+}
+
+/** One model call that fails with `message`. */
+function errorTurn(message: string): Array<StreamChunk> {
+  return [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+    },
+    { type: EventType.RUN_ERROR, message, timestamp: now() },
+  ]
+}
+
+/** One model call that asks to remove each path, one tool call per path. */
+function removeTurn(...paths: Array<string>) {
+  return toolCallTurn(
+    paths.map((path) => ({ name: 'remove', input: { path } })),
+  )
+}
+
+/** One model call that makes each tool call. */
+function toolCallTurn(
+  toolCalls: Array<{ name: string; input: unknown }>,
+): Array<StreamChunk> {
+  const calls = toolCalls.flatMap(
+    ({ name, input }, index): Array<StreamChunk> => [
+      {
+        type: EventType.TOOL_CALL_START,
+        toolCallId: `call-${index}`,
+        toolCallName: name,
+        timestamp: now(),
+      },
+      {
+        type: EventType.TOOL_CALL_ARGS,
+        toolCallId: `call-${index}`,
+        delta: JSON.stringify(input),
+        timestamp: now(),
+      },
+      {
+        type: EventType.TOOL_CALL_END,
+        toolCallId: `call-${index}`,
+        timestamp: now(),
+      },
+    ],
+  )
+  return [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+    },
+    ...calls,
+    {
+      type: EventType.RUN_FINISHED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: now(),
+      metadata: { tanstack: { finishReason: 'tool_calls' } },
+    },
+  ]
+}
+
+function deferred() {
+  let resolve: (value: void) => void = () => {}
+  const promise = new Promise<void>((done) => {
+    resolve = done
+  })
+  return { promise, resolve }
+}
+
+/**
+ * A point that work reaches and then waits at. `reached` resolves when the
+ * work arrives. The work continues after `release()`.
+ */
+function hold() {
+  const reached = deferred()
+  const released = deferred()
+  return {
+    reached: reached.promise,
+    release: () => released.resolve(),
+    async wait() {
+      reached.resolve()
+      await released.promise
+    },
+  }
+}
+
+/** A model call that waits at its `hold`, then streams `chunks`. */
+function heldTurn(chunks: Array<StreamChunk>) {
+  return { hold: hold(), chunks }
+}
+
+type ScriptedTurn = Array<StreamChunk> | ReturnType<typeof heldTurn>
+
+async function* play(turn: ScriptedTurn) {
+  if (Array.isArray(turn)) {
+    yield* turn
+    return
+  }
+  await turn.hold.wait()
+  yield* turn.chunks
+}
+
+/** A model that plays `turns` in order and keeps the messages of each call. */
+function scripted(turns: Array<ScriptedTurn>) {
+  const calls: Array<Array<ModelMessage>> = []
+  const adapter: AnyTextAdapter = {
+    kind: 'text',
+    name: 'mock',
+    model: 'mock',
+    // `~types` holds types only. Its values are never read, so they are casts.
+    '~types': {
+      providerOptions: {} as Record<string, unknown>,
+      inputModalities: ['text'] as readonly ['text'],
+      messageMetadataByModality: {
+        text: undefined as unknown,
+        image: undefined as unknown,
+        audio: undefined as unknown,
+        video: undefined as unknown,
+        document: undefined as unknown,
+      },
+      toolCapabilities: [] as ReadonlyArray<string>,
+      toolCallMetadata: undefined as unknown,
+      systemPromptMetadata: undefined as never,
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+    chatStream: (options) => {
+      const turn = turns[calls.length] ?? textTurn('')
+      calls.push(options.messages)
+      return play(turn)
+    },
+  }
+  return { adapter, calls }
+}
+
+function userTexts(messages: Array<ModelMessage> | undefined) {
+  return (messages ?? [])
+    .filter((message) => message.role === 'user')
+    .map((message) => message.content)
+}
+
+/** The MCP result of a tool call that threw an error with `message`. */
+function toolError(message: string) {
+  return { isError: true, content: [{ type: 'text', text: message }] }
+}
+
+/** The ids of the interrupts that wait, from a tool result. */
+function interruptIds(result: { structuredContent?: unknown }) {
+  return pendingShape
+    .parse(result.structuredContent)
+    .interrupts.map(({ id }) => id)
+}
+
+/**
+ * A middleware that stops the first run of a turn at `phase` with a
+ * `review` interrupt. `notes` keeps each answer that it gets.
+ */
+function reviewAt(phase: InterruptBoundaryPhase) {
+  const notes: Array<unknown> = []
+  const middleware = defineChatMiddleware({
+    onInterruptBoundary(ctx) {
+      if (ctx.parentRunId || ctx.phase !== phase) return
+      return {
+        interrupts: [
+          review.interrupt({
+            key: 'plan',
+            reason: 'review',
+            message: 'Review the plan',
+          }),
+        ],
+      }
+    },
+    onInterruptResolution(_ctx, resolutions) {
+      for (const resolution of resolutions.for(review)) {
+        if (resolution.status === 'resolved') notes.push(resolution.response)
+      }
+      return { toolResume: 'continue' }
+    },
+  })
+  return { middleware, notes }
+}
+
+/** Waits until `session` asks a question, then returns its id. */
+async function nextQuestionId(session: HarnessSession) {
+  for await (const { event } of session.events()) {
+    const isQuestion =
+      event.type === EventType.CUSTOM && event.name === HARNESS_EVENTS.question
+    if (isQuestion) return questionShape.parse(event.value).questionId
+  }
+  throw new Error('The session closed before it asked a question')
+}
+
+const pricer = defineAgent({
+  name: 'pricer',
+  description: 'Prices a vendor',
+  inputSchema: z.object({ vendor: z.string() }),
+  run: async (ctx) => `${ctx.input.vendor}: twelve dollars`,
+})
+
+const broken = defineAgent({
+  name: 'broken',
+  description: 'Always fails',
+  run: async () => {
+    throw new Error('The price list is gone.')
+  },
+})
+
+const commands = definePlugin({
+  name: 'test/commands',
+  setup: (ctx) => ({
+    commands: {
+      'connect:notion': defineCommand({
+        description: 'Sign in to Notion',
+        run: () => 'Connected to Notion.',
+      }),
+      'release/v2.1-beta': defineCommand({
+        description: 'Release the beta',
+        run: () => 'Released.',
+      }),
+      confirm: defineCommand({
+        description: 'Ask first',
+        run: async () => {
+          const sure = await ctx.session.ask({
+            message: 'Really?',
+            schema: { type: 'boolean' },
+          })
+          return sure === true ? 'Confirmed.' : 'Stopped.'
+        },
+      }),
+      greet: defineCommand({
+        description: 'Greet a person',
+        input: z.object({ name: z.string() }),
+        run: (input) => `Hello, ${input.name}.`,
+      }),
+      fail: defineCommand({
+        description: 'Always fails',
+        run: () => {
+          throw new Error('Notion is down.')
+        },
+      }),
+    },
+  }),
+})
+
+const cleanups: Array<() => Promise<unknown>> = []
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0).reverse()) await cleanup()
+})
+
+type ServerOptions = Omit<HarnessMcpServerOptions, 'host' | 'harness'>
+
+async function serve(harness: AnyHarness, options: ServerOptions = {}) {
+  const host = createHarnessHost({ persistence: memoryPersistence() })
+  cleanups.push(() => host.close())
+  const server = await createHarnessMcpServer({ host, harness, ...options })
+  return { server, host }
+}
+
+/**
+ * A harness on an MCP server. With `reviewAt`, a middleware stops the turn at
+ * that phase with a `review` interrupt.
+ */
+async function harnessServer(
+  turns: Array<ScriptedTurn>,
+  options: ServerOptions & { reviewAt?: InterruptBoundaryPhase } = {},
+) {
+  const { reviewAt: phase, ...serverOptions } = options
+  const model = scripted(turns)
+  const removed: Array<string> = []
+  const remove = toolDefinition({
+    name: 'remove',
+    description: 'Remove a file',
+    needsApproval: true,
+    inputSchema: z.object({ path: z.string() }),
+  }).server(async ({ path }) => {
+    removed.push(path)
+    return `removed ${path}`
+  })
+  // No `.server()`: the client runs it and sends the output.
+  const pickColor = toolDefinition({
+    name: 'pick_color',
+    description: 'Ask the user for a color',
+    inputSchema: z.object({ hint: z.string() }),
+    outputSchema: z.object({ color: z.string() }),
+  })
+  const reviewer = phase === undefined ? undefined : reviewAt(phase)
+  const agentHold = hold()
+  const waiter = defineAgent({
+    name: 'waiter',
+    description: 'Waits until the test releases it',
+    run: async () => {
+      await agentHold.wait()
+      return 'Done waiting.'
+    },
+  })
+  const harness = defineHarness({
+    name: 'test/mcp-harness',
+    adapter: model.adapter,
+    tools: [remove, pickColor],
+    agents: [pricer, broken, waiter],
+    expose: {
+      agents: ['pricer', 'broken', 'waiter'],
+      commands: [
+        'confirm',
+        'connect:notion',
+        'fail',
+        'greet',
+        'release/v2.1-beta',
+      ],
+    },
+    plugins: () => [commands],
+    ...(reviewer === undefined
+      ? {}
+      : { middleware: [reviewer.middleware], interrupts: [review] }),
+  })
+  const { server, host } = await serve(harness, serverOptions)
+  const session = () => host.open(harness, { threadId: 'main' })
+  return {
+    server,
+    session,
+    removed,
+    notes: reviewer?.notes ?? [],
+    calls: model.calls,
+    agentHold,
+  }
+}
+
+type ElicitReply =
+  | { action: 'accept'; content: { value: string } }
+  | { action: 'decline' }
+
+function accepted(value: string): ElicitReply {
+  return { action: 'accept', content: { value } }
+}
+
+/**
+ * A real MCP client on `server.fetch`. With `reply`, the client supports
+ * elicitation and gives that reply to every question (spec 2025 sessions
+ * only). Without it, the client speaks spec 2026 and has no elicitation.
+ */
+async function connect(
+  server: { fetch: (request: Request) => Promise<Response> },
+  options: { reply?: ElicitReply } = {},
+) {
+  const reply = options.reply
+  const client = new Client(
+    { name: 'tester', version: '1.0.0' },
+    reply === undefined
+      ? { versionNegotiation: { mode: { pin: '2026-07-28' } } }
+      : { capabilities: { elicitation: { form: {} } } },
+  )
+  const asked: Array<string> = []
+  if (reply !== undefined) {
+    client.setRequestHandler('elicitation/create', async (request) => {
+      asked.push(request.params.message)
+      return reply
+    })
+  }
+  const transport = new StreamableHTTPClientTransport(serverUrl, {
+    fetch: async (input, init) => server.fetch(new Request(input, init)),
+  })
+  await client.connect(transport)
+  cleanups.push(() => client.close())
+  return { client, asked }
+}
+
+describe('createHarnessMcpServer', () => {
+  it('lists the control tools, one tool per exposed agent, and one per exposed command', async () => {
+    const { server } = await harnessServer([])
+    const { client } = await connect(server)
+
+    const listed = await client.listTools()
+    expect(listed.tools.map((tool) => tool.name).sort()).toEqual([
+      'agent_broken',
+      'agent_pricer',
+      'agent_waiter',
+      'answer',
+      'approve',
+      'cancel',
+      'chat',
+      'command_confirm',
+      'command_connect_notion',
+      'command_fail',
+      'command_greet',
+      'command_release_v2_1_beta',
+      'reject',
+      'resolve',
+      'status',
+      'steer',
+    ])
+    const agentTool = listed.tools.find((tool) => tool.name === 'agent_pricer')
+    expect(agentTool?.description).toBe('Prices a vendor')
+    expect(Object.keys(agentTool?.inputSchema.properties ?? {})).toEqual([
+      'vendor',
+      'threadId',
+    ])
+    const commandTool = listed.tools.find(
+      (tool) => tool.name === 'command_connect_notion',
+    )
+    expect(commandTool?.description).toBe('Sign in to Notion')
+    const inputTool = listed.tools.find((tool) => tool.name === 'command_greet')
+    expect(Object.keys(inputTool?.inputSchema.properties ?? {})).toEqual([
+      'name',
+      'threadId',
+    ])
+  })
+
+  it('lists only the control tools for a harness that exposes no agents', async () => {
+    const { server } = await serve(
+      defineHarness({ name: 'test/bare', adapter: scripted([]).adapter }),
+    )
+    const { client } = await connect(server)
+
+    const listed = await client.listTools()
+    expect(listed.tools.map((tool) => tool.name).sort()).toEqual(controlTools)
+  })
+
+  it('gives command names that clash as tool names distinct tool names, in name order', async () => {
+    const clashing = definePlugin({
+      name: 'test/clashing',
+      setup: () => ({
+        commands: {
+          // Added first, but `connect:notion` comes first in name order.
+          connect_notion: defineCommand({
+            description: 'Sign in with the new flow',
+            run: () => 'New flow.',
+          }),
+          'connect:notion': defineCommand({
+            description: 'Sign in to Notion',
+            run: () => 'Connected to Notion.',
+          }),
+        },
+      }),
+    })
+    const { server } = await serve(
+      defineHarness({
+        name: 'test/clash',
+        adapter: scripted([]).adapter,
+        plugins: () => [clashing],
+        expose: { commands: ['connect_notion', 'connect:notion'] },
+      }),
+    )
+    const { client } = await connect(server)
+
+    const listed = await client.listTools()
+    const commandTools = listed.tools
+      .filter((tool) => tool.name.startsWith('command_'))
+      .map(({ name, description }) => ({ name, description }))
+      .sort((left, right) => left.name.localeCompare(right.name))
+    expect(commandTools).toEqual([
+      {
+        name: 'command_connect_notion',
+        description: 'Sign in to Notion (command connect:notion)',
+      },
+      {
+        name: 'command_connect_notion_2',
+        description: 'Sign in with the new flow (command connect_notion)',
+      },
+    ])
+    const plain = await client.callTool({
+      name: 'command_connect_notion',
+      arguments: {},
+    })
+    expect(plain.content).toEqual([
+      { type: 'text', text: 'Connected to Notion.' },
+    ])
+    const suffixed = await client.callTool({
+      name: 'command_connect_notion_2',
+      arguments: {},
+    })
+    expect(suffixed.content).toEqual([{ type: 'text', text: 'New flow.' }])
+  })
+
+  it('lists and runs only the commands in expose.commands', async () => {
+    const modes: Array<string> = []
+    const permissions = definePlugin({
+      name: 'test/permissions',
+      setup: () => ({
+        commands: {
+          mode: defineCommand({
+            description: 'Set the permission mode',
+            input: z.object({ mode: z.string() }),
+            run: (input) => {
+              modes.push(input.mode)
+              return `Mode: ${input.mode}.`
+            },
+          }),
+          undo: defineCommand({
+            description: 'Undo the last change',
+            run: () => 'Undone.',
+          }),
+        },
+      }),
+    })
+    const { server } = await serve(
+      defineHarness({
+        name: 'test/expose-commands',
+        adapter: scripted([]).adapter,
+        plugins: () => [permissions],
+        expose: { commands: ['undo'] },
+      }),
+    )
+    const { client } = await connect(server)
+
+    const listed = await client.listTools()
+    const commandTools = listed.tools
+      .map((tool) => tool.name)
+      .filter((name) => name.startsWith('command_'))
+    expect(commandTools).toEqual(['command_undo'])
+
+    await expect(
+      client.callTool({ name: 'command_mode', arguments: { mode: 'bypass' } }),
+    ).rejects.toThrow('Tool command_mode not found')
+    expect(modes).toEqual([])
+
+    const undone = await client.callTool({
+      name: 'command_undo',
+      arguments: {},
+    })
+    expect(undone.content).toEqual([{ type: 'text', text: 'Undone.' }])
+  })
+
+  it.each([
+    {
+      options: {},
+      expected: { name: 'test/mcp-harness', version: '1.0.0' },
+    },
+    {
+      options: { name: 'desk', version: '2.1.0' },
+      expected: { name: 'desk', version: '2.1.0' },
+    },
+  ])(
+    'names the server $expected.name $expected.version',
+    async ({ options, expected }) => {
+      const { server } = await harnessServer([], options)
+      const { client } = await connect(server)
+
+      expect(client.getServerVersion()).toMatchObject(expected)
+    },
+  )
+
+  it('chat returns the answer of the turn', async () => {
+    const { server } = await harnessServer([
+      textTurn('Hello from the harness.'),
+    ])
+    const { client } = await connect(server)
+
+    const reply = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'hi' },
+    })
+    expect(reply.structuredContent).toEqual({
+      status: 'completed',
+      text: 'Hello from the harness.',
+      interrupts: [],
+      questions: [],
+    })
+  })
+
+  it('returns a failed model call as a tool error', async () => {
+    const { server } = await harnessServer([errorTurn('The model is down.')])
+    const { client } = await connect(server)
+
+    const reply = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'hi' },
+    })
+    expect(reply).toMatchObject(toolError('The model is down.'))
+  })
+
+  it('returns a tool that needs approval as pending, and approve runs it', async () => {
+    const { server, removed } = await harnessServer([
+      removeTurn('a.txt'),
+      textTurn('Removed a.txt.'),
+    ])
+    const { client } = await connect(server)
+
+    const pending = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'remove a.txt' },
+    })
+    expect(pending.structuredContent).toEqual({
+      status: 'interrupted',
+      text: '',
+      interrupts: [
+        {
+          id: expect.any(String),
+          kind: 'approval',
+          tool: 'remove',
+          args: { path: 'a.txt' },
+          message: 'Approval required to run remove',
+          responseSchema: removeApprovalSchema,
+        },
+      ],
+      questions: [],
+    })
+    expect(removed).toEqual([])
+
+    const status = await client.callTool({ name: 'status', arguments: {} })
+    expect(status.structuredContent).toMatchObject({
+      status: 'requires_action',
+      interrupts: [{ kind: 'approval', tool: 'remove' }],
+      agents: [],
+      queuedTurns: 0,
+    })
+
+    const approved = await client.callTool({ name: 'approve', arguments: {} })
+    expect(approved.structuredContent).toEqual({
+      status: 'completed',
+      text: 'Removed a.txt.',
+      interrupts: [],
+      questions: [],
+    })
+    expect(removed).toEqual(['a.txt'])
+  })
+
+  it('reject continues the turn without running the tool', async () => {
+    const { server, removed } = await harnessServer([
+      removeTurn('a.txt'),
+      textTurn('Kept a.txt.'),
+    ])
+    const { client } = await connect(server)
+
+    await client.callTool({
+      name: 'chat',
+      arguments: { message: 'remove a.txt' },
+    })
+    const rejected = await client.callTool({ name: 'reject', arguments: {} })
+    expect(rejected.structuredContent).toEqual({
+      status: 'completed',
+      text: 'Kept a.txt.',
+      interrupts: [],
+      questions: [],
+    })
+    expect(removed).toEqual([])
+  })
+
+  it('refuses approve when no approval waits', async () => {
+    const { server } = await harnessServer([])
+    const { client } = await connect(server)
+
+    const refused = await client.callTool({ name: 'approve', arguments: {} })
+    expect(refused).toMatchObject(toolError('No approvals are waiting.'))
+  })
+
+  it('refuses a resolve that does not answer every open interrupt', async () => {
+    const { server, removed } = await harnessServer([
+      removeTurn('a.txt', 'b.txt'),
+      textTurn('Removed one file.'),
+    ])
+    const { client } = await connect(server)
+
+    const pending = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'remove both files' },
+    })
+    const ids = interruptIds(pending)
+    expect(ids).toHaveLength(2)
+    const [first, second] = ids
+
+    const partial = await client.callTool({
+      name: 'resolve',
+      arguments: { decisions: [{ interruptId: first, approved: true }] },
+    })
+    expect(partial).toMatchObject(
+      toolError(
+        `resolve must answer every open interrupt. Missing: ${second}.`,
+      ),
+    )
+    expect(removed).toEqual([])
+
+    const mixed = await client.callTool({
+      name: 'resolve',
+      arguments: {
+        decisions: [
+          { interruptId: first, approved: true },
+          { interruptId: second, approved: false },
+        ],
+      },
+    })
+    expect(mixed.structuredContent).toMatchObject({
+      status: 'completed',
+      text: 'Removed one file.',
+    })
+    expect(removed).toEqual(['a.txt'])
+  })
+
+  it('refuses a resolve that names an interrupt that is not open', async () => {
+    const { server, removed } = await harnessServer([removeTurn('a.txt')])
+    const { client } = await connect(server)
+
+    const pending = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'remove a.txt' },
+    })
+    const [open] = interruptIds(pending)
+
+    const refused = await client.callTool({
+      name: 'resolve',
+      arguments: {
+        decisions: [
+          { interruptId: open, approved: true },
+          { interruptId: 'ghost', approved: true },
+        ],
+      },
+    })
+    expect(refused).toMatchObject(
+      toolError('These interrupts are not open: ghost.'),
+    )
+    expect(removed).toEqual([])
+  })
+
+  it('returns the harness refusal of a resolve as a tool error', async () => {
+    const { server } = await harnessServer([])
+    const { client } = await connect(server)
+
+    const refused = await client.callTool({
+      name: 'resolve',
+      arguments: { decisions: [] },
+    })
+    expect(refused).toMatchObject(
+      toolError('The harness refused the decisions: no_pending_interrupts.'),
+    )
+  })
+
+  it("approves every tool call on its own with approvals 'auto'", async () => {
+    const { server, removed } = await harnessServer(
+      [removeTurn('a.txt'), textTurn('Removed a.txt.')],
+      { approvals: 'auto' },
+    )
+    const { client } = await connect(server)
+
+    const reply = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'remove a.txt' },
+    })
+    expect(reply.structuredContent).toEqual({
+      status: 'completed',
+      text: 'Removed a.txt.',
+      interrupts: [],
+      questions: [],
+    })
+    expect(removed).toEqual(['a.txt'])
+  })
+
+  it('asks the user about an approval when the client supports elicitation', async () => {
+    const { server, removed } = await harnessServer([
+      removeTurn('a.txt'),
+      textTurn('Removed a.txt.'),
+    ])
+    const { client, asked } = await connect(server, { reply: accepted('yes') })
+
+    const reply = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'remove a.txt' },
+    })
+    expect(reply.structuredContent).toMatchObject({
+      status: 'completed',
+      text: 'Removed a.txt.',
+    })
+    expect(removed).toEqual(['a.txt'])
+    expect(asked).toEqual([
+      'Approval required to run remove. Arguments: {"path":"a.txt"}. Approve? Answer yes or no.',
+    ])
+  })
+
+  it('rejects the tool call when the user answers no', async () => {
+    const { server, removed } = await harnessServer([
+      removeTurn('a.txt'),
+      textTurn('Kept a.txt.'),
+    ])
+    const { client } = await connect(server, { reply: accepted('no') })
+
+    const reply = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'remove a.txt' },
+    })
+    expect(reply.structuredContent).toEqual({
+      status: 'completed',
+      text: 'Kept a.txt.',
+      interrupts: [],
+      questions: [],
+    })
+    expect(removed).toEqual([])
+  })
+
+  it('returns the approval as pending when the user declines the question', async () => {
+    const { server, removed } = await harnessServer([removeTurn('a.txt')])
+    const { client, asked } = await connect(server, {
+      reply: { action: 'decline' },
+    })
+
+    const reply = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'remove a.txt' },
+    })
+    expect(reply.structuredContent).toMatchObject({
+      status: 'interrupted',
+      interrupts: [
+        { kind: 'approval', tool: 'remove', args: { path: 'a.txt' } },
+      ],
+    })
+    expect(asked).toHaveLength(1)
+    expect(removed).toEqual([])
+  })
+
+  it('returns a generic interrupt with its kind and schema, and resolve answers it with a payload', async () => {
+    const { server, notes } = await harnessServer(
+      [textTurn('Here is the plan.'), textTurn('Plan approved.')],
+      { reviewAt: 'afterModel' },
+    )
+    const { client } = await connect(server)
+
+    const pending = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'make a plan' },
+    })
+    expect(pending.structuredContent).toEqual({
+      status: 'interrupted',
+      text: 'Here is the plan.',
+      interrupts: [
+        {
+          id: expect.any(String),
+          kind: 'generic',
+          message: 'Review the plan',
+          responseSchema: reviewSchema,
+        },
+      ],
+      questions: [],
+    })
+    const [id] = interruptIds(pending)
+
+    const refused = await client.callTool({ name: 'approve', arguments: {} })
+    expect(refused).toMatchObject(
+      toolError(`Use resolve: interrupt ${id} needs a payload.`),
+    )
+
+    const resolved = await client.callTool({
+      name: 'resolve',
+      arguments: {
+        decisions: [{ interruptId: id, payload: { note: 'Ship it.' } }],
+      },
+    })
+    expect(resolved.structuredContent).toEqual({
+      status: 'completed',
+      text: 'Plan approved.',
+      interrupts: [],
+      questions: [],
+    })
+    expect(notes).toEqual([{ note: 'Ship it.' }])
+  })
+
+  it("approvals 'auto' leaves a generic interrupt pending", async () => {
+    const { server, notes } = await harnessServer(
+      [textTurn('Here is the plan.')],
+      { approvals: 'auto', reviewAt: 'afterModel' },
+    )
+    const { client } = await connect(server)
+
+    const reply = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'make a plan' },
+    })
+    expect(reply.structuredContent).toMatchObject({
+      status: 'interrupted',
+      interrupts: [{ kind: 'generic', message: 'Review the plan' }],
+    })
+    expect(notes).toEqual([])
+  })
+
+  it('resolves an approval and a generic interrupt of one turn in one call', async () => {
+    const { server, removed, notes } = await harnessServer(
+      [removeTurn('a.txt'), textTurn('Removed a.txt.')],
+      { approvals: 'auto', reviewAt: 'beforeTools' },
+    )
+    const { client } = await connect(server)
+
+    const pending = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'remove a.txt' },
+    })
+    // 'auto' answers approvals only. The review is open, so both wait.
+    expect(pending.structuredContent).toMatchObject({
+      status: 'interrupted',
+      interrupts: [{ kind: 'approval', tool: 'remove' }, { kind: 'generic' }],
+    })
+    expect(removed).toEqual([])
+    const [approval, reviewId] = interruptIds(pending)
+
+    const resolved = await client.callTool({
+      name: 'resolve',
+      arguments: {
+        decisions: [
+          { interruptId: approval, approved: true },
+          { interruptId: reviewId, payload: { note: 'Go ahead.' } },
+        ],
+      },
+    })
+    expect(resolved.structuredContent).toEqual({
+      status: 'completed',
+      text: 'Removed a.txt.',
+      interrupts: [],
+      questions: [],
+    })
+    expect(removed).toEqual(['a.txt'])
+    expect(notes).toEqual([{ note: 'Go ahead.' }])
+  })
+
+  it.each([
+    {
+      given: 'no approved and no payload for an approval',
+      approval: {},
+      reviewDecision: { payload: { note: 'Go ahead.' } },
+      refused: 0,
+      problem: 'needs approved or payload.',
+    },
+    {
+      given: 'only approved for a generic interrupt',
+      approval: { approved: true },
+      reviewDecision: { approved: true },
+      refused: 1,
+      problem: 'needs a payload. It is not an approval.',
+    },
+  ])(
+    'refuses a decision with $given',
+    async ({ approval, reviewDecision, refused, problem }) => {
+      const { server, removed, notes } = await harnessServer(
+        [removeTurn('a.txt')],
+        { reviewAt: 'beforeTools' },
+      )
+      const { client } = await connect(server)
+
+      const pending = await client.callTool({
+        name: 'chat',
+        arguments: { message: 'remove a.txt' },
+      })
+      const ids = interruptIds(pending)
+      const [approvalId, reviewId] = ids
+
+      const reply = await client.callTool({
+        name: 'resolve',
+        arguments: {
+          decisions: [
+            { interruptId: approvalId, ...approval },
+            { interruptId: reviewId, ...reviewDecision },
+          ],
+        },
+      })
+      expect(reply).toMatchObject(
+        toolError(`The decision for ${ids[refused]} ${problem}`),
+      )
+      const status = await client.callTool({ name: 'status', arguments: {} })
+      expect(status.structuredContent).toMatchObject({
+        status: 'requires_action',
+        interrupts: [{ kind: 'approval' }, { kind: 'generic' }],
+      })
+      expect(removed).toEqual([])
+      expect(notes).toEqual([])
+    },
+  )
+
+  it('returns a client tool call as pending, and resolve sends its output', async () => {
+    const { server, calls } = await harnessServer([
+      toolCallTurn([{ name: 'pick_color', input: { hint: 'sky' } }]),
+      textTurn('Blue it is.'),
+    ])
+    const { client } = await connect(server)
+
+    const pending = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'pick a color' },
+    })
+    expect(pending.structuredContent).toMatchObject({
+      status: 'interrupted',
+      interrupts: [
+        {
+          kind: 'client-tool',
+          tool: 'pick_color',
+          args: { hint: 'sky' },
+          message: 'Client tool pick_color is ready to run',
+        },
+      ],
+    })
+    const [id] = interruptIds(pending)
+
+    const resolved = await client.callTool({
+      name: 'resolve',
+      arguments: {
+        decisions: [{ interruptId: id, payload: { color: 'blue' } }],
+      },
+    })
+    expect(resolved.structuredContent).toMatchObject({
+      status: 'completed',
+      text: 'Blue it is.',
+    })
+    const toolResults = (calls[1] ?? []).filter(
+      (message) => message.role === 'tool',
+    )
+    expect(toolResults).toMatchObject([
+      { toolCallId: 'call-0', content: '{"color":"blue"}' },
+    ])
+  })
+
+  it('answer resolves the question of a command and returns its result', async () => {
+    const { server } = await harnessServer([])
+    const { client } = await connect(server)
+
+    const waiting = await client.callTool({
+      name: 'command_confirm',
+      arguments: {},
+    })
+    expect(waiting.structuredContent).toEqual({
+      status: 'waiting',
+      interrupts: [],
+      questions: [
+        {
+          id: expect.any(String),
+          message: 'Really?',
+          schema: { type: 'boolean' },
+        },
+      ],
+    })
+    const [question] = pendingShape.parse(waiting.structuredContent).questions
+    if (question === undefined) throw new Error('The command asked nothing')
+
+    const answered = await client.callTool({
+      name: 'answer',
+      arguments: { questionId: question.id, value: true },
+    })
+    expect(answered.content).toEqual([{ type: 'text', text: 'Confirmed.' }])
+  })
+
+  it('answer returns answered for a question that no tool call waits on', async () => {
+    const { server, session } = await harnessServer([])
+    const { client } = await connect(server)
+    const live = await session()
+    const confirm = live.command('confirm')
+    const questionId = await nextQuestionId(live)
+
+    const answered = await client.callTool({
+      name: 'answer',
+      arguments: { questionId, value: true },
+    })
+    expect(answered.structuredContent).toEqual({
+      status: 'answered',
+      interrupts: [],
+      questions: [],
+    })
+    expect(await confirm).toBe('Confirmed.')
+  })
+
+  it('returns the harness refusal of an answer as a tool error', async () => {
+    const { server } = await harnessServer([])
+    const { client } = await connect(server)
+
+    const refused = await client.callTool({
+      name: 'answer',
+      arguments: { questionId: 'q-unknown', value: true },
+    })
+    expect(refused).toMatchObject(
+      toolError('The harness refused the answer: unknown_question.'),
+    )
+  })
+
+  it('agent_<name> runs the agent and returns its result', async () => {
+    const { server } = await harnessServer([])
+    const { client } = await connect(server)
+
+    const result = await client.callTool({
+      name: 'agent_pricer',
+      arguments: { vendor: 'Acme' },
+    })
+    expect(result.content).toEqual([
+      { type: 'text', text: 'Acme: twelve dollars' },
+    ])
+  })
+
+  it('returns the error of a failed agent as a tool error', async () => {
+    const { server } = await harnessServer([])
+    const { client } = await connect(server)
+
+    const result = await client.callTool({
+      name: 'agent_broken',
+      arguments: {},
+    })
+    expect(result).toMatchObject(toolError('The price list is gone.'))
+  })
+
+  it('command_<name> runs the command under a tool-safe name', async () => {
+    const { server } = await harnessServer([])
+    const { client } = await connect(server)
+
+    const result = await client.callTool({
+      name: 'command_connect_notion',
+      arguments: {},
+    })
+    expect(result.content).toEqual([
+      { type: 'text', text: 'Connected to Notion.' },
+    ])
+  })
+
+  it('command_<name> takes the command input next to threadId', async () => {
+    const { server } = await harnessServer([])
+    const { client } = await connect(server)
+
+    const result = await client.callTool({
+      name: 'command_greet',
+      arguments: { name: 'Ada', threadId: 'main' },
+    })
+    expect(result.content).toEqual([{ type: 'text', text: 'Hello, Ada.' }])
+  })
+
+  it('returns the error of a failed command as a tool error', async () => {
+    const { server } = await harnessServer([])
+    const { client } = await connect(server)
+
+    const result = await client.callTool({
+      name: 'command_fail',
+      arguments: {},
+    })
+    expect(result).toMatchObject(toolError('Notion is down.'))
+  })
+
+  it('steer starts a turn when no turn runs', async () => {
+    const { server, calls } = await harnessServer([
+      textTurn('Tabs it is.'),
+      textTurn('Formatted.'),
+    ])
+    const { client } = await connect(server)
+
+    const steered = await client.callTool({
+      name: 'steer',
+      arguments: { message: 'use tabs' },
+    })
+    expect(steered.structuredContent).toEqual({
+      inputId: expect.any(String),
+      status: 'accepted',
+      operationId: expect.any(String),
+    })
+    const reply = await client.callTool({
+      name: 'chat',
+      arguments: { message: 'format it' },
+    })
+    expect(reply.structuredContent).toMatchObject({ text: 'Formatted.' })
+    expect(userTexts(calls[0])).toEqual(['use tabs'])
+    expect(userTexts(calls[1])).toEqual(['use tabs', 'format it'])
+  })
+
+  it('cancel stops the running turn, and its chat call ends with an error', async () => {
+    const held = heldTurn(textTurn('Too late.'))
+    const { server } = await harnessServer([held])
+    const { client } = await connect(server)
+
+    const reply = client.callTool({
+      name: 'chat',
+      arguments: { message: 'write a long story' },
+    })
+    await held.hold.reached
+    const cancelled = await client.callTool({ name: 'cancel', arguments: {} })
+    expect(cancelled.structuredContent).toEqual({
+      inputId: expect.any(String),
+      status: 'accepted',
+      operationId: expect.any(String),
+    })
+    held.hold.release()
+    expect(await reply).toMatchObject(toolError('Cancelled.'))
+  })
+
+  it('returns the refusal of cancel when no turn runs', async () => {
+    const { server } = await harnessServer([])
+    const { client } = await connect(server)
+
+    const refused = await client.callTool({ name: 'cancel', arguments: {} })
+    expect(refused.structuredContent).toEqual({
+      inputId: expect.any(String),
+      status: 'rejected',
+      reason: 'not_running',
+    })
+  })
+
+  it('status shows the running agents and the queued turns', async () => {
+    const held = heldTurn(textTurn('Busy.'))
+    const { server, session, agentHold } = await harnessServer([
+      held,
+      textTurn('Follow-up done.'),
+    ])
+    const { client } = await connect(server)
+
+    const turn = client.callTool({
+      name: 'chat',
+      arguments: { message: 'work' },
+    })
+    await held.hold.reached
+    await (await session()).followUp('then this')
+    const agent = client.callTool({ name: 'agent_waiter', arguments: {} })
+    await agentHold.reached
+
+    const status = await client.callTool({ name: 'status', arguments: {} })
+    expect(status.structuredContent).toEqual({
+      status: 'running',
+      interrupts: [],
+      questions: [],
+      agents: [{ id: expect.any(String), agent: 'waiter' }],
+      queuedTurns: 1,
+    })
+    held.hold.release()
+    agentHold.release()
+    await Promise.all([turn, agent])
+  })
+
+  it('keeps a separate conversation per threadId', async () => {
+    const { server, calls } = await harnessServer([
+      textTurn('one'),
+      textTurn('two'),
+      textTurn('three'),
+    ])
+    const { client } = await connect(server)
+
+    const threads = [
+      { message: 'first', threadId: 'a' },
+      { message: 'second', threadId: 'b' },
+      { message: 'third', threadId: 'a' },
+    ]
+    for (const input of threads) {
+      await client.callTool({ name: 'chat', arguments: input })
+    }
+    expect(userTexts(calls[1])).toEqual(['second'])
+    expect(userTexts(calls[2])).toEqual(['first', 'third'])
+  })
+
+  it.each([
+    { options: {}, thread: 'main' },
+    { options: { threadId: 'desk' }, thread: 'desk' },
+  ])(
+    'uses thread $thread for a call without threadId',
+    async ({ options, thread }) => {
+      const { server, calls } = await harnessServer(
+        [textTurn('one'), textTurn('two')],
+        options,
+      )
+      const { client } = await connect(server)
+
+      await client.callTool({ name: 'chat', arguments: { message: 'first' } })
+      await client.callTool({
+        name: 'chat',
+        arguments: { message: 'second', threadId: thread },
+      })
+      expect(userTexts(calls[1])).toEqual(['first', 'second'])
+    },
+  )
+})
diff --git a/packages/ai-mcp/tests/protected-server.ts b/packages/ai-mcp/tests/protected-server.ts
new file mode 100644
index 0000000000..a9b4e7ad59
--- /dev/null
+++ b/packages/ai-mcp/tests/protected-server.ts
@@ -0,0 +1,170 @@
+import { createServer } from 'node:http'
+import { z } from 'zod'
+import {
+  McpServer,
+  WebStandardStreamableHTTPServerTransport,
+} from '@modelcontextprotocol/server'
+import type { IncomingMessage, Server } from 'node:http'
+
+/** Copy the Node request headers into Web `Headers`. */
+function webHeaders(req: IncomingMessage) {
+  const headers = new Headers()
+  const entries = Object.entries(req.headersDistinct)
+  for (const [name, values] of entries) {
+    for (const value of values ?? []) headers.append(name, value)
+  }
+  return headers
+}
+
+/**
+ * A local MCP server behind OAuth, like Notion's or Linear's: protected
+ * resource metadata, authorization server metadata, dynamic client
+ * registration, a token endpoint, and an `echo` tool.
+ *
+ * - The code `code-1` gives `access-1` and `refresh-1`.
+ * - The code `code-2` gives only `access-1` (no refresh token, expiry, or scope).
+ * - The refresh token `refresh-1` gives `access-2` (and no new refresh token).
+ * - `revoke(token)` makes the MCP endpoint refuse a token.
+ */
+export async function startProtectedServer(
+  options: {
+    /** Advertise that callbacks carry `iss` (RFC 9207), as Linear does. */
+    issParameter?: boolean
+  } = {},
+) {
+  const seen = {
+    registrations: [] as Array<Record<string, unknown>>,
+    tokenRequests: [] as Array<URLSearchParams>,
+  }
+  const valid = new Set(['access-1'])
+  let base = ''
+  const readBody = async (req: IncomingMessage) => {
+    const chunks: Array<Buffer> = []
+    for await (const chunk of req) chunks.push(chunk as Buffer)
+    return Buffer.concat(chunks).toString('utf8')
+  }
+  const server: Server = createServer((req, res) => {
+    void (async () => {
+      const url = new URL(req.url ?? '/', base)
+      const json = (status: number, value: unknown) => {
+        res.writeHead(status, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify(value))
+      }
+      if (url.pathname.startsWith('/.well-known/oauth-protected-resource')) {
+        return json(200, {
+          resource: `${base}/mcp`,
+          authorization_servers: [base],
+        })
+      }
+      if (url.pathname.startsWith('/.well-known/oauth-authorization-server')) {
+        return json(200, {
+          issuer: base,
+          authorization_endpoint: `${base}/authorize`,
+          token_endpoint: `${base}/token`,
+          registration_endpoint: `${base}/register`,
+          response_types_supported: ['code'],
+          grant_types_supported: ['authorization_code', 'refresh_token'],
+          code_challenge_methods_supported: ['S256'],
+          token_endpoint_auth_methods_supported: ['none'],
+          ...(options.issParameter
+            ? { authorization_response_iss_parameter_supported: true }
+            : {}),
+        })
+      }
+      if (url.pathname === '/register' && req.method === 'POST') {
+        const metadata = JSON.parse(await readBody(req))
+        seen.registrations.push(metadata)
+        return json(201, { ...metadata, client_id: 'client-1' })
+      }
+      if (url.pathname === '/token' && req.method === 'POST') {
+        const form = new URLSearchParams(await readBody(req))
+        seen.tokenRequests.push(form)
+        if (
+          form.get('grant_type') === 'authorization_code' &&
+          form.get('code') === 'code-1'
+        ) {
+          return json(200, {
+            access_token: 'access-1',
+            refresh_token: 'refresh-1',
+            token_type: 'Bearer',
+            expires_in: 3600,
+            scope: 'read write',
+          })
+        }
+        if (
+          form.get('grant_type') === 'authorization_code' &&
+          form.get('code') === 'code-2'
+        ) {
+          return json(200, { access_token: 'access-1', token_type: 'Bearer' })
+        }
+        if (
+          form.get('grant_type') === 'refresh_token' &&
+          form.get('refresh_token') === 'refresh-1'
+        ) {
+          valid.add('access-2')
+          return json(200, { access_token: 'access-2', token_type: 'Bearer' })
+        }
+        return json(400, { error: 'invalid_grant' })
+      }
+      if (url.pathname === '/mcp') {
+        const token = (req.headers.authorization ?? '').replace(/^Bearer /, '')
+        if (!valid.has(token)) {
+          res.writeHead(401, {
+            'WWW-Authenticate': `Bearer resource_metadata="${base}/.well-known/oauth-protected-resource"`,
+          })
+          res.end()
+          return
+        }
+        if (req.method !== 'POST') {
+          res.writeHead(405).end()
+          return
+        }
+        const mcp = new McpServer({ name: 'protected', version: '1.0.0' })
+        mcp.registerTool(
+          'echo',
+          {
+            description: 'Echo text',
+            inputSchema: { text: z.string() },
+            annotations: { readOnlyHint: true },
+          },
+          async ({ text }) => ({
+            content: [{ type: 'text' as const, text: `echo: ${text}` }],
+          }),
+        )
+        const transport = new WebStandardStreamableHTTPServerTransport({
+          sessionIdGenerator: undefined,
+          enableJsonResponse: true,
+        })
+        await mcp.connect(transport)
+        const response = await transport.handleRequest(
+          new Request(url, {
+            method: req.method,
+            headers: webHeaders(req),
+            body: await readBody(req),
+          }),
+        )
+        res.writeHead(response.status, Object.fromEntries(response.headers))
+        res.end(await response.text())
+        return
+      }
+      res.writeHead(404).end()
+    })()
+  })
+  await new Promise<void>((resolve) =>
+    server.listen(0, '127.0.0.1', () => resolve()),
+  )
+  const address = server.address()
+  base = `http://127.0.0.1:${typeof address === 'object' && address ? address.port : 0}`
+  return {
+    url: `${base}/mcp`,
+    /** The `issuer` of the authorization server metadata. */
+    issuer: base,
+    seen,
+    revoke: (token: string) => valid.delete(token),
+    close: () =>
+      new Promise<void>((resolve) => {
+        server.closeAllConnections()
+        server.close(() => resolve())
+      }),
+  }
+}
diff --git a/packages/ai-mcp/vite.config.ts b/packages/ai-mcp/vite.config.ts
index 5b6c74c28c..a0d3ac34d4 100644
--- a/packages/ai-mcp/vite.config.ts
+++ b/packages/ai-mcp/vite.config.ts
@@ -31,6 +31,8 @@ export default mergeConfig(
       './src/apps/index.ts',
       './src/server/index.ts',
       './src/server/stdio.ts',
+      './src/connector.ts',
+      './src/harness.ts',
     ],
     srcDir: './src',
     cjs: false,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1d1ca10bf6..f64634dd3d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -892,8 +892,8 @@ importers:
         specifier: ^1.168.42
         version: 1.168.42(@tanstack/react-router@1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(esbuild@0.28.1)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.2.1(@types/node@24.10.3)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass@1.101.0)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.2.1(@types/node@24.10.3)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass@1.101.0)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
       '@tanstack/store':
-        specifier: ^0.8.0
-        version: 0.8.0
+        specifier: ^0.11.1
+        version: 0.11.2
       framer-motion:
         specifier: ^11.15.0
         version: 11.18.2(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
@@ -1197,8 +1197,8 @@ importers:
         specifier: ^1.168.42
         version: 1.168.42(@tanstack/react-router@1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(esbuild@0.28.1)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.2.1(@types/node@24.10.3)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass@1.101.0)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.2.1(@types/node@24.10.3)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass@1.101.0)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
       '@tanstack/store':
-        specifier: ^0.8.0
-        version: 0.8.0
+        specifier: ^0.11.1
+        version: 0.11.2
       dockerode:
         specifier: ^4.0.2
         version: 4.0.12(supports-color@7.2.0)
@@ -1795,8 +1795,8 @@ importers:
         specifier: ^0.8.0
         version: 0.8.0(solid-js@1.9.10)
       '@tanstack/store':
-        specifier: ^0.8.0
-        version: 0.8.0
+        specifier: ^0.11.1
+        version: 0.11.2
       highlight.js:
         specifier: ^11.11.1
         version: 11.11.1
@@ -2591,6 +2591,10 @@ importers:
         version: 8.2.1(@types/node@24.10.3)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass@1.101.0)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
 
   packages/ai-harness:
+    dependencies:
+      '@tanstack/store':
+        specifier: ^0.11.1
+        version: 0.11.2
     devDependencies:
       '@tanstack/ai':
         specifier: workspace:*
@@ -2755,6 +2759,12 @@ importers:
         specifier: ^6.2.12
         version: 6.2.12
     devDependencies:
+      '@tanstack/ai-harness':
+        specifier: workspace:*
+        version: link:../ai-harness
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../ai-persistence
       '@vitest/coverage-v8':
         specifier: 4.1.10
         version: 4.1.10(vitest@4.1.11)
diff --git a/testing/e2e/fixtures/harness-turn/basic.json b/testing/e2e/fixtures/harness-turn/basic.json
new file mode 100644
index 0000000000..1309e2739e
--- /dev/null
+++ b/testing/e2e/fixtures/harness-turn/basic.json
@@ -0,0 +1,29 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "[harness-retry] try twice",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "error": { "message": "Service Unavailable", "type": "server_error" },
+        "status": 503
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-retry] try twice",
+        "sequenceIndex": 1
+      },
+      "response": { "content": "Back after a retry." }
+    },
+    {
+      "match": { "userMessage": "[harness-finish] post it" },
+      "response": { "content": "Draft answer." }
+    },
+    {
+      "match": { "userMessage": "[harness-finish] reminder: post the answer" },
+      "response": { "content": "Posted answer." }
+    }
+  ]
+}
diff --git a/testing/e2e/fixtures/harness/agent-messages.json b/testing/e2e/fixtures/harness/agent-messages.json
new file mode 100644
index 0000000000..e246761b71
--- /dev/null
+++ b/testing/e2e/fixtures/harness/agent-messages.json
@@ -0,0 +1,12 @@
+{
+  "fixtures": [
+    {
+      "match": { "userMessage": "[harness-agent-msg] keep it short" },
+      "response": { "content": "Short draft." }
+    },
+    {
+      "match": { "userMessage": "[harness-agent-msg] add a title" },
+      "response": { "content": "Titled draft." }
+    }
+  ]
+}
diff --git a/testing/e2e/fixtures/harness/media.json b/testing/e2e/fixtures/harness/media.json
new file mode 100644
index 0000000000..8565402a86
--- /dev/null
+++ b/testing/e2e/fixtures/harness/media.json
@@ -0,0 +1,37 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "[harness-media] paint a copy of this dot",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "painter",
+            "arguments": "{\"prompt\":\"[harness-media-image] a blue dot\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-media] paint a copy of this dot",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Here is your blue dot."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-media-image] a blue dot"
+      },
+      "response": {
+        "image": {
+          "b64Json": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR42mNgYPgPAAEDAQA2dBFAAAAAAElFTkSuQmCC"
+        }
+      }
+    }
+  ]
+}
diff --git a/testing/e2e/fixtures/harness/protocol-inputs.json b/testing/e2e/fixtures/harness/protocol-inputs.json
new file mode 100644
index 0000000000..4dccc0d312
--- /dev/null
+++ b/testing/e2e/fixtures/harness/protocol-inputs.json
@@ -0,0 +1,299 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "[harness-background] build it",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "slowBuild",
+            "arguments": "{}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-background] build it",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "The build runs in the background."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-background-done]"
+      },
+      "response": {
+        "content": "The build is done."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-revert] first"
+      },
+      "response": {
+        "content": "First answer."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-revert] second"
+      },
+      "response": {
+        "content": "Second answer."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-rejoin] ask my name",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "askName",
+            "arguments": "{}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-rejoin] ask my name",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Hello, Otto."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-runid] deploy prod",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "deploy",
+            "arguments": "{\"env\":\"prod\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-runid] deploy prod",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Deployed to prod."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-fast-resolve] deploy stage",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "deploy",
+            "arguments": "{\"env\":\"stage\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-fast-resolve] deploy stage",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Deployed to stage."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-chatclient] deploy dev",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "deploy",
+            "arguments": "{\"env\":\"dev\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-chatclient] deploy dev",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Deployed to dev."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-context] probe",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "probe",
+            "arguments": "{}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-context] probe",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Probed the context."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-sender] who am i",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "whoami",
+            "arguments": "{}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-sender] who am i",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "You are the sender."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-queue] ask my name",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "askName",
+            "arguments": "{}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-queue-moved] say it now"
+      },
+      "response": {
+        "content": "Hello, Otto. I got the moved message."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-continue] name a color",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "content": "Red."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-continue] name a color",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Blue."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-ephemeral-prompt] note"
+      },
+      "response": {
+        "content": "Apple."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-ephemeral-continue] name a color"
+      },
+      "response": {
+        "content": "Red."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-ephemeral-continue] note"
+      },
+      "response": {
+        "content": "Green."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-elicit] what is the forecast",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "weather_ask_city",
+            "arguments": "{}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-elicit] what is the forecast",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "The forecast for Paris is sunny."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-elicit-2025] book a trip",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "trips_book_trip",
+            "arguments": "{}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-elicit-2025] book a trip",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Your trip to Paris is booked, seat 12A."
+      }
+    }
+  ]
+}
diff --git a/testing/e2e/fixtures/harness/protocol.json b/testing/e2e/fixtures/harness/protocol.json
new file mode 100644
index 0000000000..82a2c6b813
--- /dev/null
+++ b/testing/e2e/fixtures/harness/protocol.json
@@ -0,0 +1,20 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "[harness-protocol] hello"
+      },
+      "response": {
+        "content": "Hello over the harness protocol."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[harness-durable] run once"
+      },
+      "response": {
+        "content": "Stored once."
+      }
+    }
+  ]
+}
diff --git a/testing/e2e/fixtures/harness/thread-controls.json b/testing/e2e/fixtures/harness/thread-controls.json
new file mode 100644
index 0000000000..8a8a0fbf08
--- /dev/null
+++ b/testing/e2e/fixtures/harness/thread-controls.json
@@ -0,0 +1,50 @@
+{
+  "fixtures": [
+    {
+      "match": { "userMessage": "[harness-usage] hello" },
+      "response": { "content": "Counted." }
+    },
+    {
+      "match": { "userMessage": "[harness-settings] hi" },
+      "response": { "content": "Strong." }
+    },
+    {
+      "match": { "userMessage": "[harness-cwd] start" },
+      "response": { "content": "Started." }
+    },
+    {
+      "match": { "userMessage": "[harness-cwd] where" },
+      "response": { "content": "Moved." }
+    },
+    {
+      "match": { "userMessage": "[harness-reset] first" },
+      "response": { "content": "First answer." }
+    },
+    {
+      "match": { "userMessage": "[harness-reset] second" },
+      "response": { "content": "Second answer." }
+    },
+    {
+      "match": { "userMessage": "[harness-fork] one" },
+      "response": { "content": "One." }
+    },
+    {
+      "match": { "userMessage": "[harness-fork] two" },
+      "response": { "content": "Two." }
+    },
+    {
+      "match": { "userMessage": "[harness-chips] one" },
+      "response": { "content": "Chips one." }
+    },
+    {
+      "match": { "userMessage": "[harness-chips] two" },
+      "response": { "content": "Chips two." }
+    },
+    {
+      "match": {
+        "userMessage": "Background agent stepper finished: [stepper finished] charged once"
+      },
+      "response": { "content": "The stepper finished." }
+    }
+  ]
+}
diff --git a/testing/e2e/src/lib/harness-protocol-tools.ts b/testing/e2e/src/lib/harness-protocol-tools.ts
new file mode 100644
index 0000000000..15784a495e
--- /dev/null
+++ b/testing/e2e/src/lib/harness-protocol-tools.ts
@@ -0,0 +1,41 @@
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+/**
+ * Tools of the harness protocol route. The specs import the same
+ * definitions, so a `ChatClient` knows `deploy` is an approval.
+ */
+export const deploy = toolDefinition({
+  name: 'deploy',
+  description: 'Deploy to an environment. Needs approval.',
+  needsApproval: true,
+  inputSchema: z.object({ env: z.string() }),
+})
+
+/** Returns the context of the turn, so a spec can see what a tool got. */
+export const probe = toolDefinition({
+  name: 'probe',
+  description: 'Show the context of this turn.',
+  inputSchema: z.object({}),
+})
+
+/** Asks the user for a name, so the turn keeps running until the answer. */
+export const askName = toolDefinition({
+  name: 'askName',
+  description: 'Ask the user for their name.',
+  inputSchema: z.object({}),
+})
+
+/** Returns the id of the principal that the turn runs as. */
+export const whoami = toolDefinition({
+  name: 'whoami',
+  description: 'Show who runs this turn.',
+  inputSchema: z.object({}),
+})
+
+/** Builds until the test sends `release`, so a spec can move it to the background. */
+export const slowBuild = toolDefinition({
+  name: 'slowBuild',
+  description: 'Build the project. It takes a while.',
+  inputSchema: z.object({}),
+})
diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index d7fe95be71..5faf38a2e9 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -106,6 +106,7 @@ import { Route as ApiMcpAppsCallRouteImport } from './routes/api.mcp-apps-call'
 import { Route as ApiMcpAppsChatRouteImport } from './routes/api.mcp-apps-chat'
 import { Route as ApiMcpAppsServerRouteImport } from './routes/api.mcp-apps-server'
 import { Route as ApiMcpInputServerRouteImport } from './routes/api.mcp-input-server'
+import { Route as ApiMcpLegacyInputServerRouteImport } from './routes/api.mcp-legacy-input-server'
 import { Route as ApiMcpInputTestRouteImport } from './routes/api.mcp-input-test'
 import { Route as ApiMcpLifecycleTestRouteImport } from './routes/api.mcp-lifecycle-test'
 import { Route as ApiMcpManagedTestRouteImport } from './routes/api.mcp-managed-test'
@@ -175,6 +176,7 @@ import { Route as ApiWebMcpPageToolsRouteImport } from './routes/api.web-mcp-pag
 import { Route as ApiWorldRouteImport } from './routes/api.world'
 import { Route as ApiWrapFetchWireRouteImport } from './routes/api.wrap-fetch-wire'
 import { Route as ApiAudioStreamRouteImport } from './routes/api.audio.stream'
+import { Route as ApiHarnessProtocolSplatRouteImport } from './routes/api.harness-protocol.$'
 import { Route as ApiImageStreamRouteImport } from './routes/api.image.stream'
 import { Route as ApiTranscriptionStreamRouteImport } from './routes/api.transcription.stream'
 import { Route as ApiTtsStreamRouteImport } from './routes/api.tts.stream'
@@ -685,6 +687,11 @@ const ApiMcpInputServerRoute = ApiMcpInputServerRouteImport.update({
   path: '/api/mcp-input-server',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiMcpLegacyInputServerRoute = ApiMcpLegacyInputServerRouteImport.update({
+  id: '/api/mcp-legacy-input-server',
+  path: '/api/mcp-legacy-input-server',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiMcpInputTestRoute = ApiMcpInputTestRouteImport.update({
   id: '/api/mcp-input-test',
   path: '/api/mcp-input-test',
@@ -1051,6 +1058,11 @@ const ApiAudioStreamRoute = ApiAudioStreamRouteImport.update({
   path: '/stream',
   getParentRoute: () => ApiAudioRoute,
 } as any)
+const ApiHarnessProtocolSplatRoute = ApiHarnessProtocolSplatRouteImport.update({
+  id: '/api/harness-protocol/$',
+  path: '/api/harness-protocol/$',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiImageStreamRoute = ApiImageStreamRouteImport.update({
   id: '/stream',
   path: '/stream',
@@ -1169,6 +1181,7 @@ export interface FileRoutesByFullPath {
   '/api/mcp-apps-chat': typeof ApiMcpAppsChatRoute
   '/api/mcp-apps-server': typeof ApiMcpAppsServerRoute
   '/api/mcp-input-server': typeof ApiMcpInputServerRoute
+  '/api/mcp-legacy-input-server': typeof ApiMcpLegacyInputServerRoute
   '/api/mcp-input-test': typeof ApiMcpInputTestRoute
   '/api/mcp-lifecycle-test': typeof ApiMcpLifecycleTestRoute
   '/api/mcp-managed-test': typeof ApiMcpManagedTestRoute
@@ -1239,6 +1252,7 @@ export interface FileRoutesByFullPath {
   '/api/wrap-fetch-wire': typeof ApiWrapFetchWireRoute
   '/$provider/': typeof ProviderIndexRoute
   '/api/audio/stream': typeof ApiAudioStreamRoute
+  '/api/harness-protocol/$': typeof ApiHarnessProtocolSplatRoute
   '/api/image/stream': typeof ApiImageStreamRoute
   '/api/transcription/stream': typeof ApiTranscriptionStreamRoute
   '/api/tts/stream': typeof ApiTtsStreamRoute
@@ -1341,6 +1355,7 @@ export interface FileRoutesByTo {
   '/api/mcp-apps-chat': typeof ApiMcpAppsChatRoute
   '/api/mcp-apps-server': typeof ApiMcpAppsServerRoute
   '/api/mcp-input-server': typeof ApiMcpInputServerRoute
+  '/api/mcp-legacy-input-server': typeof ApiMcpLegacyInputServerRoute
   '/api/mcp-input-test': typeof ApiMcpInputTestRoute
   '/api/mcp-lifecycle-test': typeof ApiMcpLifecycleTestRoute
   '/api/mcp-managed-test': typeof ApiMcpManagedTestRoute
@@ -1411,6 +1426,7 @@ export interface FileRoutesByTo {
   '/api/wrap-fetch-wire': typeof ApiWrapFetchWireRoute
   '/$provider': typeof ProviderIndexRoute
   '/api/audio/stream': typeof ApiAudioStreamRoute
+  '/api/harness-protocol/$': typeof ApiHarnessProtocolSplatRoute
   '/api/image/stream': typeof ApiImageStreamRoute
   '/api/transcription/stream': typeof ApiTranscriptionStreamRoute
   '/api/tts/stream': typeof ApiTtsStreamRoute
@@ -1514,6 +1530,7 @@ export interface FileRoutesById {
   '/api/mcp-apps-chat': typeof ApiMcpAppsChatRoute
   '/api/mcp-apps-server': typeof ApiMcpAppsServerRoute
   '/api/mcp-input-server': typeof ApiMcpInputServerRoute
+  '/api/mcp-legacy-input-server': typeof ApiMcpLegacyInputServerRoute
   '/api/mcp-input-test': typeof ApiMcpInputTestRoute
   '/api/mcp-lifecycle-test': typeof ApiMcpLifecycleTestRoute
   '/api/mcp-managed-test': typeof ApiMcpManagedTestRoute
@@ -1584,6 +1601,7 @@ export interface FileRoutesById {
   '/api/wrap-fetch-wire': typeof ApiWrapFetchWireRoute
   '/$provider/': typeof ProviderIndexRoute
   '/api/audio/stream': typeof ApiAudioStreamRoute
+  '/api/harness-protocol/$': typeof ApiHarnessProtocolSplatRoute
   '/api/image/stream': typeof ApiImageStreamRoute
   '/api/transcription/stream': typeof ApiTranscriptionStreamRoute
   '/api/tts/stream': typeof ApiTtsStreamRoute
@@ -1688,6 +1706,7 @@ export interface FileRouteTypes {
     | '/api/mcp-apps-chat'
     | '/api/mcp-apps-server'
     | '/api/mcp-input-server'
+    | '/api/mcp-legacy-input-server'
     | '/api/mcp-input-test'
     | '/api/mcp-lifecycle-test'
     | '/api/mcp-managed-test'
@@ -1758,6 +1777,7 @@ export interface FileRouteTypes {
     | '/api/wrap-fetch-wire'
     | '/$provider/'
     | '/api/audio/stream'
+    | '/api/harness-protocol/$'
     | '/api/image/stream'
     | '/api/transcription/stream'
     | '/api/tts/stream'
@@ -1860,6 +1880,7 @@ export interface FileRouteTypes {
     | '/api/mcp-apps-chat'
     | '/api/mcp-apps-server'
     | '/api/mcp-input-server'
+    | '/api/mcp-legacy-input-server'
     | '/api/mcp-input-test'
     | '/api/mcp-lifecycle-test'
     | '/api/mcp-managed-test'
@@ -1930,6 +1951,7 @@ export interface FileRouteTypes {
     | '/api/wrap-fetch-wire'
     | '/$provider'
     | '/api/audio/stream'
+    | '/api/harness-protocol/$'
     | '/api/image/stream'
     | '/api/transcription/stream'
     | '/api/tts/stream'
@@ -2032,6 +2054,7 @@ export interface FileRouteTypes {
     | '/api/mcp-apps-chat'
     | '/api/mcp-apps-server'
     | '/api/mcp-input-server'
+    | '/api/mcp-legacy-input-server'
     | '/api/mcp-input-test'
     | '/api/mcp-lifecycle-test'
     | '/api/mcp-managed-test'
@@ -2102,6 +2125,7 @@ export interface FileRouteTypes {
     | '/api/wrap-fetch-wire'
     | '/$provider/'
     | '/api/audio/stream'
+    | '/api/harness-protocol/$'
     | '/api/image/stream'
     | '/api/transcription/stream'
     | '/api/tts/stream'
@@ -2205,6 +2229,7 @@ export interface RootRouteChildren {
   ApiMcpAppsChatRoute: typeof ApiMcpAppsChatRoute
   ApiMcpAppsServerRoute: typeof ApiMcpAppsServerRoute
   ApiMcpInputServerRoute: typeof ApiMcpInputServerRoute
+  ApiMcpLegacyInputServerRoute: typeof ApiMcpLegacyInputServerRoute
   ApiMcpInputTestRoute: typeof ApiMcpInputTestRoute
   ApiMcpLifecycleTestRoute: typeof ApiMcpLifecycleTestRoute
   ApiMcpManagedTestRoute: typeof ApiMcpManagedTestRoute
@@ -2274,6 +2299,7 @@ export interface RootRouteChildren {
   ApiWorldRoute: typeof ApiWorldRoute
   ApiWrapFetchWireRoute: typeof ApiWrapFetchWireRoute
   ProviderIndexRoute: typeof ProviderIndexRoute
+  ApiHarnessProtocolSplatRoute: typeof ApiHarnessProtocolSplatRoute
 }
 
 declare module '@tanstack/react-router' {
@@ -2957,6 +2983,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiMcpInputServerRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/mcp-legacy-input-server': {
+      id: '/api/mcp-legacy-input-server'
+      path: '/api/mcp-legacy-input-server'
+      fullPath: '/api/mcp-legacy-input-server'
+      preLoaderRoute: typeof ApiMcpLegacyInputServerRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/mcp-input-test': {
       id: '/api/mcp-input-test'
       path: '/api/mcp-input-test'
@@ -3440,6 +3473,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiAudioStreamRouteImport
       parentRoute: typeof ApiAudioRoute
     }
+    '/api/harness-protocol/$': {
+      id: '/api/harness-protocol/$'
+      path: '/api/harness-protocol/$'
+      fullPath: '/api/harness-protocol/$'
+      preLoaderRoute: typeof ApiHarnessProtocolSplatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/image/stream': {
       id: '/api/image/stream'
       path: '/stream'
@@ -3631,6 +3671,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiMcpAppsChatRoute: ApiMcpAppsChatRoute,
   ApiMcpAppsServerRoute: ApiMcpAppsServerRoute,
   ApiMcpInputServerRoute: ApiMcpInputServerRoute,
+  ApiMcpLegacyInputServerRoute: ApiMcpLegacyInputServerRoute,
   ApiMcpInputTestRoute: ApiMcpInputTestRoute,
   ApiMcpLifecycleTestRoute: ApiMcpLifecycleTestRoute,
   ApiMcpManagedTestRoute: ApiMcpManagedTestRoute,
@@ -3701,6 +3742,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiWorldRoute: ApiWorldRoute,
   ApiWrapFetchWireRoute: ApiWrapFetchWireRoute,
   ProviderIndexRoute: ProviderIndexRoute,
+  ApiHarnessProtocolSplatRoute: ApiHarnessProtocolSplatRoute,
 }
 export const routeTree = rootRouteImport
   ._addFileChildren(rootRouteChildren)
diff --git a/testing/e2e/src/routes/api.harness-protocol.$.ts b/testing/e2e/src/routes/api.harness-protocol.$.ts
new file mode 100644
index 0000000000..7f979ab5fe
--- /dev/null
+++ b/testing/e2e/src/routes/api.harness-protocol.$.ts
@@ -0,0 +1,332 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { defineAgent } from '@tanstack/ai'
+import { createOpenaiChat } from '@tanstack/ai-openai'
+import {
+  type FinishContext,
+  retryTransientErrors,
+  configOption,
+  createHarnessHandler,
+  createHarnessHost,
+  defineCommand,
+  defineHarness,
+  definePlugin,
+} from '@tanstack/ai-harness'
+import { mcp } from '@tanstack/ai-mcp/harness'
+import { memoryLogStore, memoryPersistence } from '@tanstack/ai-persistence'
+import { z } from 'zod'
+import {
+  askName,
+  deploy,
+  probe,
+  slowBuild,
+  whoami,
+} from '@/lib/harness-protocol-tools'
+import { createImageAdapter } from '@/lib/media-providers'
+import { createTextAdapter } from '@/lib/providers'
+
+/**
+ * The harness session protocol behind `createHarnessHandler`. The main
+ * model is the OpenAI adapter against aimock. The aimock port and test id
+ * come from headers, so one handler serves every test. The model can call
+ * `painter`, which makes one image with the OpenAI image adapter. The
+ * harness keeps that image, and the uploads, in memory.
+ */
+// One host for every test. Each test uses its own thread ids, and a signed
+// media URL comes without the test headers.
+const host = createHarnessHost({ persistence: memoryPersistence() })
+// A durable host: a session log and run leases. A request picks it with the
+// `x-harness-durable: 1` header.
+const durableHost = createHarnessHost({
+  persistence: {
+    stores: { log: memoryLogStore(), runs: memoryPersistence().stores.runs },
+  },
+})
+
+// Two users, so a test can share one thread between them.
+const authorize = (req: Request) => {
+  const token = req.headers.get('authorization')
+  if (token === 'Bearer e2e-token') return { id: 'e2e' }
+  if (token === 'Bearer e2e-token-bob') return { id: 'bob' }
+  return null
+}
+
+// The `drafter` and `slowBuild` of each test wait until the test sends the
+// `release` command, so the test can act while they wait.
+// ponytail: one gate per test id, kept for the life of the server.
+const drafterGates = new Map<
+  string,
+  { open: () => void; opened: Promise<void> }
+>()
+function drafterGate(testId: string) {
+  let entry = drafterGates.get(testId)
+  if (!entry) {
+    let open = () => {}
+    const opened = new Promise<void>((resolve) => {
+      open = resolve
+    })
+    entry = { open, opened }
+    drafterGates.set(testId, entry)
+  }
+  return entry
+}
+
+function harnessFor(request: Request) {
+  const testId = request.headers.get('x-test-id') ?? 'default'
+  const port = Number(request.headers.get('x-aimock-port') ?? '4010')
+  const painter = defineAgent({
+    name: 'painter',
+    description: 'Paints one image',
+    inputSchema: z.object({ prompt: z.string() }),
+    run: async (ctx) => {
+      await ctx.generateImage({
+        adapter: createImageAdapter('openai', port, testId),
+        prompt: ctx.input.prompt,
+      })
+      return 'Painted one image.'
+    },
+  })
+  // `x-harness-turn` picks the turn hooks for a test.
+  const turnMode = request.headers.get('x-harness-turn')
+  const reminder = '[harness-finish] reminder: post the answer'
+  const turn =
+    turnMode === 'retry'
+      ? { onModelError: retryTransientErrors({ baseDelayMs: 1 }) }
+      : turnMode === 'finish'
+        ? {
+            beforeFinish: ({ messages }: FinishContext) =>
+              messages.some((message) => message.content === reminder)
+                ? undefined
+                : { messages: [{ role: 'user' as const, content: reminder }] },
+          }
+        : turnMode === 'ephemeral'
+          ? {
+              // The transcript never gets an ephemeral reminder, so the hook
+              // counts its cycles to send it once.
+              beforeFinish: ({ cycle }: FinishContext) =>
+                cycle === 0
+                  ? {
+                      ephemeral: [{ role: 'user' as const, content: reminder }],
+                    }
+                  : undefined,
+            }
+          : undefined
+  // The retry test needs the harness to see the 503, so the SDK must not retry.
+  const adapter =
+    turnMode === 'retry'
+      ? createOpenaiChat('gpt-4o', 'sk-e2e-test-dummy-key', {
+          baseURL: `http://127.0.0.1:${port}/v1`,
+          defaultHeaders: { 'X-Test-Id': testId },
+          maxRetries: 0,
+        })
+      : createTextAdapter('openai', undefined, port, testId).adapter
+  // `x-harness-mcp: 1` connects the `api.mcp-input-server` route. Its
+  // `ask_city` tool asks the user for a city by MCP elicitation.
+  // `x-harness-mcp: 2025` connects the spec 2025 `api.mcp-legacy-input-server`
+  // route. Its `book_trip` tool asks twice in one call.
+  const mcpMode = request.headers.get('x-harness-mcp')
+  const servers =
+    mcpMode === '1'
+      ? [
+          mcp({
+            servers: {
+              weather: {
+                type: 'http',
+                url: new URL('/api/mcp-input-server', request.url).href,
+              },
+            },
+          }),
+        ]
+      : mcpMode === '2025'
+        ? [
+            mcp({
+              servers: {
+                trips: {
+                  type: 'http',
+                  url: new URL('/api/mcp-legacy-input-server', request.url)
+                    .href,
+                },
+              },
+            }),
+          ]
+        : []
+  const harness = defineHarness({
+    name: 'e2e/protocol',
+    adapter,
+    // App data in the session index entry: the context items a user pinned
+    // in the composer. Each write over `POST sessions` checks it.
+    metadataSchema: z.object({ chips: z.array(z.string()) }),
+    // Models a thread can pick with `configure`. aimock answers both, and
+    // its journal shows which model id a turn sent.
+    models: {
+      fast: createTextAdapter('openai', 'gpt-4o-mini', port, testId).adapter,
+      strong: createTextAdapter('openai', 'gpt-4.1', port, testId).adapter,
+    },
+    ...(turn ? { turn } : {}),
+    tools: [
+      deploy.server(async ({ env }) => ({ deployed: env })),
+      // The input's context, from `forwardedProps` on POST run.
+      probe.server(async (_input, toolContext) => ({
+        context: toolContext?.context ?? null,
+      })),
+      // It supports `detach`, so a client can move it to the background.
+      slowBuild.server((_input, toolContext) => {
+        const work = drafterGate(testId).opened.then(() => ({
+          built: '[harness-background-done]',
+        }))
+        const detach = toolContext?.detach
+        return detach ? Promise.race([work, detach(work)]) : work
+      }),
+    ],
+    subagents: { agents: [painter] },
+    agents: [
+      defineAgent({
+        name: 'echo',
+        description: 'Echoes its input',
+        inputSchema: z.object({ text: z.string() }),
+        run: async (ctx) => ctx.input.text,
+      }),
+      defineAgent({
+        name: 'drafter',
+        description: 'Drafts a post when the test releases it',
+        inputSchema: z.object({ topic: z.string() }),
+        run: async (ctx) => {
+          await drafterGate(testId).opened
+          // A first run starts from the topic. A follow-up run continues the
+          // drafter's own transcript, which ends with the follow-up.
+          return ctx.chat({
+            adapter: createTextAdapter('openai', undefined, port, testId)
+              .adapter,
+            messages:
+              ctx.messages.length > 0
+                ? ctx.messages
+                : [{ role: 'user', content: ctx.input.topic }],
+          })
+        },
+      }),
+    ],
+    expose: {
+      agents: ['echo', 'drafter'],
+      settings: ['model', 'instructions', 'cwd'],
+      config: ['tone'],
+      // `undo` lets a client revert and unrevert the transcript.
+      commands: ['greet', 'release', 'undo'],
+    },
+    plugins: () => [
+      ...servers,
+      // The sender of the running turn, as plugins see it.
+      definePlugin({
+        name: 'e2e/whoami',
+        setup: (ctx) => ({
+          tools: [
+            whoami.server(async () => ({
+              id: ctx.session.principal?.id ?? null,
+            })),
+          ],
+        }),
+      }),
+      // A tool that waits for an answer, so a turn stays running.
+      definePlugin({
+        name: 'e2e/ask',
+        setup: (ctx) => ({
+          tools: [
+            askName.server(async () => ({
+              name: await ctx.session.ask({
+                message: 'What is your name?',
+                schema: z.string(),
+              }),
+            })),
+          ],
+        }),
+      }),
+      definePlugin({
+        name: 'e2e/settings',
+        setup: () => ({
+          config: {
+            tone: configOption.select({
+              options: ['plain', 'warm'],
+              default: 'plain',
+            }),
+          },
+          commands: {
+            greet: defineCommand({
+              description: 'Say hello',
+              run: () => 'hello',
+            }),
+          },
+        }),
+      }),
+      // Lets the `drafter` of this test make its model call.
+      definePlugin({
+        name: 'e2e/drafter',
+        setup: () => ({
+          commands: {
+            release: defineCommand({
+              description: 'Let the drafter go on',
+              run: () => {
+                drafterGate(testId).open()
+                return 'released'
+              },
+            }),
+          },
+        }),
+      }),
+    ],
+  })
+  return {
+    harness,
+    host: request.headers.get('x-harness-durable') === '1' ? durableHost : host,
+  }
+}
+
+function handlerFor(request: Request) {
+  const { harness, host: hostOf } = harnessFor(request)
+  return createHarnessHandler({
+    host: hostOf,
+    harness,
+    authorize,
+    // Test only: every principal may use every thread.
+    canAccess: () => true,
+    // Each request makes a new handler, so a fixed secret keeps a signed URL
+    // working on the next request.
+    mediaSecret: 'e2e-media-secret',
+  })
+}
+
+/**
+ * Test only: `POST .../fork` with `{ threadId, newThreadId, at? }` forks a
+ * thread with `host.fork` and answers with the transcript of the new thread.
+ * The handler forks with `POST .../sessions`, which picks the new thread id.
+ * Here the test picks it, so a test can fork onto a thread that has messages.
+ */
+async function forkThread(request: Request) {
+  const principal = authorize(request)
+  if (!principal)
+    return Response.json({ error: 'unauthorized' }, { status: 401 })
+  const { harness, host: hostOf } = harnessFor(request)
+  const body = (await request.json()) as {
+    threadId: string
+    newThreadId: string
+    at?: string
+  }
+  try {
+    const forked = await hostOf.fork(harness, { ...body, principal })
+    return Response.json({ transcript: await forked.transcript() })
+  } catch (error) {
+    return Response.json(
+      { error: error instanceof Error ? error.message : String(error) },
+      { status: 400 },
+    )
+  }
+}
+
+export const Route = createFileRoute('/api/harness-protocol/$')({
+  server: {
+    handlers: {
+      GET: ({ request }) => handlerFor(request)(request),
+      POST: ({ request }) =>
+        new URL(request.url).pathname.endsWith('/fork')
+          ? forkThread(request)
+          : handlerFor(request)(request),
+    },
+  },
+})
diff --git a/testing/e2e/src/routes/api.mcp-legacy-input-server.ts b/testing/e2e/src/routes/api.mcp-legacy-input-server.ts
new file mode 100644
index 0000000000..979316a9f2
--- /dev/null
+++ b/testing/e2e/src/routes/api.mcp-legacy-input-server.ts
@@ -0,0 +1,46 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { toolDefinition } from '@tanstack/ai'
+import { createMCPServer } from '@tanstack/ai-mcp/server'
+import type { MCPToolContext } from '@tanstack/ai-mcp/server'
+import { z } from 'zod'
+
+/**
+ * A spec 2025 MCP server built with `createMCPServer`.
+ *
+ * `book_trip` asks the user twice in one call: a city, then a seat. On spec
+ * 2025 each question is an `elicitation/create` request to the client.
+ */
+const bookTrip = toolDefinition({
+  name: 'book_trip',
+  description: 'Ask the user for a city and a seat, then book the trip',
+  inputSchema: z.object({}),
+}).server<MCPToolContext>(async (_args, ctx) => {
+  const city = await ctx.context.requestInput({ message: 'Which city?' })
+  const seat = await ctx.context.requestInput({ message: 'Which seat?' })
+  return `Booked ${String(city)}, seat ${String(seat)}`
+})
+
+const server = createMCPServer({
+  name: 'trips-legacy',
+  version: '1.0.0',
+  tools: [bookTrip],
+  sessions: 'memory',
+})
+
+/** A spec 2026 request carries `mcp-method`. Refuse it, so the client uses 2025. */
+function handle(request: Request) {
+  if (request.headers.get('mcp-method') !== null) {
+    return new Response('This server speaks only spec 2025.', { status: 400 })
+  }
+  return server.fetch(request)
+}
+
+export const Route = createFileRoute('/api/mcp-legacy-input-server')({
+  server: {
+    handlers: {
+      GET: ({ request }) => handle(request),
+      POST: ({ request }) => handle(request),
+      DELETE: ({ request }) => handle(request),
+    },
+  },
+})
diff --git a/testing/e2e/tests/harness-agent-messages.spec.ts b/testing/e2e/tests/harness-agent-messages.spec.ts
new file mode 100644
index 0000000000..9620a5a8e9
--- /dev/null
+++ b/testing/e2e/tests/harness-agent-messages.spec.ts
@@ -0,0 +1,150 @@
+import { test, expect } from './fixtures'
+import type { APIRequestContext } from '@playwright/test'
+
+/**
+ * Messages to a running background agent over the harness protocol. A steer
+ * joins the agent's next model call, and a follow-up runs the agent again
+ * on its own transcript. The agent waits for the `release` command, so the
+ * steer arrives before its model call. aimock's journal shows what each
+ * model call sent.
+ */
+
+type JournalEntry = {
+  headers?: Record<string, string>
+  body: { messages?: Array<{ role: string; content: unknown }> } | null
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null
+
+/** A journal entry with a `headers` record and a `messages` array body. */
+function isJournalEntry(value: unknown): value is JournalEntry {
+  if (!isRecord(value) || !isRecord(value.headers)) return false
+  const { body } = value
+  if (body === null) return true
+  if (!isRecord(body)) return false
+  return (
+    body.messages === undefined ||
+    (Array.isArray(body.messages) &&
+      body.messages.every(
+        (message) => isRecord(message) && typeof message.role === 'string',
+      ))
+  )
+}
+
+function client(
+  request: APIRequestContext,
+  testId: string,
+  aimockPort: number,
+) {
+  const headers = {
+    authorization: 'Bearer e2e-token',
+    'x-test-id': testId,
+    'x-aimock-port': String(aimockPort),
+  }
+  const json = { ...headers, 'content-type': 'application/json' }
+  const control = async (threadId: string, input: unknown) =>
+    (
+      await request.post('/api/harness-protocol/control', {
+        headers: json,
+        data: { threadId, input },
+      })
+    ).json()
+  const snapshot = async (threadId: string) =>
+    (
+      await request.get(`/api/harness-protocol/snapshot?threadId=${threadId}`, {
+        headers,
+      })
+    ).json()
+  /** This test's model calls, in order, from aimock's journal. */
+  const modelCalls = async () => {
+    const journal = await request.get(
+      `http://127.0.0.1:${aimockPort}/v1/_requests`,
+    )
+    const entries: unknown = await journal.json()
+    return (Array.isArray(entries) ? entries : [])
+      .filter(isJournalEntry)
+      .filter((entry) => entry.headers?.['x-test-id'] === testId)
+  }
+  return { control, snapshot, modelCalls }
+}
+
+/** The text of every message a model call sent, one per line. */
+const textOf = (entry: JournalEntry | undefined) =>
+  (entry?.body?.messages ?? [])
+    .map((message) =>
+      typeof message.content === 'string'
+        ? message.content
+        : JSON.stringify(message.content),
+    )
+    .join('\n')
+
+test.describe('harness agent messages', () => {
+  test('steers a running agent, then runs it again with a follow-up', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = client(request, testId, aimockPort)
+    const threadId = `agent-msg-${testId}`
+    const started = await user.control(threadId, {
+      op: 'agent',
+      agent: 'drafter',
+      input: { topic: '[harness-agent-msg] draft a post' },
+    })
+    expect(started).toMatchObject({ status: 'accepted' })
+
+    const steer = await user.control(threadId, {
+      op: 'agentMessage',
+      operationId: started.operationId,
+      message: '[harness-agent-msg] keep it short',
+    })
+    expect(steer).toMatchObject({
+      status: 'accepted',
+      operationId: started.operationId,
+    })
+    expect(
+      await user.control(threadId, { op: 'command', name: 'release' }),
+    ).toMatchObject({ status: 'accepted' })
+
+    await expect.poll(async () => (await user.modelCalls()).length).toBe(1)
+    const [first] = await user.modelCalls()
+    expect(textOf(first)).toContain('[harness-agent-msg] draft a post')
+    expect(textOf(first)).toContain('[harness-agent-msg] keep it short')
+
+    // The run ended: no operation is active.
+    await expect
+      .poll(async () => (await user.snapshot(threadId)).activeOperations.length)
+      .toBe(0)
+    const followUp = await user.control(threadId, {
+      op: 'agentMessage',
+      operationId: started.operationId,
+      message: '[harness-agent-msg] add a title',
+      mode: 'followUp',
+    })
+    expect(followUp).toMatchObject({ status: 'accepted' })
+    expect(followUp.operationId).not.toBe(started.operationId)
+
+    await expect.poll(async () => (await user.modelCalls()).length).toBe(2)
+    const second = (await user.modelCalls())[1]
+    expect(textOf(second)).toContain('Short draft.')
+    expect(textOf(second).endsWith('[harness-agent-msg] add a title')).toBe(
+      true,
+    )
+  })
+
+  test('refuses a message to a run it does not know', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = client(request, testId, aimockPort)
+    expect(
+      await user.control(`agent-msg-${testId}`, {
+        op: 'agentMessage',
+        operationId: 'op-agent-none',
+        message: 'Hello.',
+      }),
+    ).toMatchObject({ status: 'rejected', reason: 'not_running' })
+  })
+})
diff --git a/testing/e2e/tests/harness-media.spec.ts b/testing/e2e/tests/harness-media.spec.ts
new file mode 100644
index 0000000000..cf7a46e955
--- /dev/null
+++ b/testing/e2e/tests/harness-media.spec.ts
@@ -0,0 +1,189 @@
+import { test, expect } from './fixtures'
+import type { APIRequestContext } from '@playwright/test'
+import type { MediaRecord } from '@tanstack/ai-harness'
+
+const BASE = '/api/harness-protocol'
+
+// A 1x1 red PNG that the user sends, and the 1x1 blue PNG that the image
+// agent makes (the aimock image in fixtures/harness/media.json).
+const RED_DOT = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR42mP4z8AAAAMBAQD3A0FDAAAAAElFTkSuQmCC',
+  'base64',
+)
+const BLUE_DOT = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR42mNgYPgPAAEDAQA2dBFAAAAAAElFTkSuQmCC',
+  'base64',
+)
+
+/** The media routes of the protocol handler, as the e2e principal. */
+function mediaApi(
+  request: APIRequestContext,
+  testId: string,
+  aimockPort: number,
+) {
+  const headers = {
+    authorization: 'Bearer e2e-token',
+    'x-test-id': testId,
+    'x-aimock-port': String(aimockPort),
+  }
+  return {
+    headers,
+    /** Upload `bytes` as a PNG file of `threadId`. */
+    async upload(threadId: string, bytes: Buffer) {
+      const query = new URLSearchParams({ threadId, name: 'dot.png' })
+      const response = await request.post(`${BASE}/media?${query}`, {
+        headers: { ...headers, 'content-type': 'image/png' },
+        data: bytes,
+      })
+      const record: MediaRecord = await response.json()
+      return record
+    },
+    /** The signed URL of a file, from the media-url route. */
+    async signedUrl(record: MediaRecord) {
+      const query = new URLSearchParams({
+        threadId: record.threadId,
+        id: record.id,
+      })
+      const response = await request.get(`${BASE}/media-url?${query}`, {
+        headers,
+      })
+      const body: { path: string } = await response.json()
+      return `${BASE}/${body.path}`
+    },
+  }
+}
+
+test.describe('harness media', () => {
+  test('serves an uploaded image from its signed URL without auth', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const api = mediaApi(request, testId, aimockPort)
+    const record = await api.upload(`media-${testId}`, RED_DOT)
+
+    const response = await request.get(await api.signedUrl(record))
+
+    expect(record).toMatchObject({
+      threadId: `media-${testId}`,
+      kind: 'image',
+      mimeType: 'image/png',
+      name: 'dot.png',
+      size: RED_DOT.byteLength,
+      source: 'user',
+    })
+    expect(response.status()).toBe(200)
+    expect(await response.body()).toEqual(RED_DOT)
+    expect(response.headers()).toMatchObject({
+      'content-type': 'image/png',
+      'x-content-type-options': 'nosniff',
+      'content-security-policy': "default-src 'none'; sandbox",
+    })
+  })
+
+  test('refuses a signed URL whose file id was changed (403)', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const api = mediaApi(request, testId, aimockPort)
+    const record = await api.upload(`media-sig-${testId}`, RED_DOT)
+    const other = await api.upload(`media-sig-${testId}`, BLUE_DOT)
+    const url = new URL(await api.signedUrl(record), 'http://e2e')
+
+    url.searchParams.set('id', other.id)
+    const response = await request.get(`${url.pathname}${url.search}`)
+
+    expect(response.status()).toBe(403)
+  })
+
+  test('a prompt with an uploaded image runs the image agent, and its image loads from a signed URL', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const api = mediaApi(request, testId, aimockPort)
+    const threadId = `media-run-${testId}`
+    const upload = await api.upload(threadId, RED_DOT)
+
+    // AG-UI text parts carry `text`. The media part has the TanStack shape.
+    const run = await request.post(`${BASE}/run`, {
+      headers: { ...api.headers, 'content-type': 'application/json' },
+      data: {
+        threadId,
+        // The run id is also the input id, so each test needs its own.
+        runId: `media-run-${testId}`,
+        messages: [
+          {
+            id: 'u1',
+            role: 'user',
+            content: [
+              {
+                type: 'text',
+                text: '[harness-media] paint a copy of this dot',
+              },
+              {
+                type: 'image',
+                source: {
+                  type: 'url',
+                  value: `harness-media:${upload.id}`,
+                  mimeType: 'image/png',
+                },
+              },
+            ],
+          },
+        ],
+        tools: [],
+        context: [],
+        state: {},
+        forwardedProps: {},
+      },
+    })
+    const events = (await run.text())
+      .split('\n')
+      .filter((line) => line.startsWith('data: '))
+      .map((line) => JSON.parse(line.slice(6)))
+    // The stream also has the painter's own message. The last one is the
+    // model's answer.
+    const texts = events.filter(
+      (event) => event.type === 'TEXT_MESSAGE_CONTENT',
+    )
+    const answer = texts
+      .filter((event) => event.messageId === texts.at(-1)?.messageId)
+      .map((event) => event.delta)
+      .join('')
+    const painted: MediaRecord = events.find(
+      (event) => event.type === 'CUSTOM' && event.name === 'harness.media',
+    )?.value
+
+    expect(answer).toBe('Here is your blue dot.')
+    expect(painted).toMatchObject({
+      threadId,
+      kind: 'image',
+      mimeType: 'image/png',
+      size: BLUE_DOT.byteLength,
+      source: 'generated',
+      subagentRunId: expect.stringMatching(/^subagent-/),
+    })
+
+    const image = await request.get(await api.signedUrl(painted))
+
+    expect(image.status()).toBe(200)
+    expect(image.headers()['content-type']).toBe('image/png')
+    expect(await image.body()).toEqual(BLUE_DOT)
+
+    // The painter's own messages load again by its run id, only from this thread.
+    const childOf = async (thread: string) => {
+      const query = new URLSearchParams({
+        threadId: thread,
+        subagentRunId: painted.subagentRunId ?? '',
+      })
+      const response = await request.get(`${BASE}/agent-transcript?${query}`, {
+        headers: api.headers,
+      })
+      return JSON.stringify(await response.json())
+    }
+    expect(await childOf(threadId)).toContain('Painted one image.')
+    expect(await childOf(`media-other-${testId}`)).toBe('[]')
+  })
+})
diff --git a/testing/e2e/tests/harness-protocol-inputs.spec.ts b/testing/e2e/tests/harness-protocol-inputs.spec.ts
new file mode 100644
index 0000000000..541ec3b9c4
--- /dev/null
+++ b/testing/e2e/tests/harness-protocol-inputs.spec.ts
@@ -0,0 +1,767 @@
+import { ChatClient, fetchServerSentEvents } from '@tanstack/ai-client'
+import { deploy } from '../src/lib/harness-protocol-tools'
+import { test, expect } from './fixtures'
+import type { APIRequestContext } from '@playwright/test'
+
+type Chunk = {
+  type: string
+  runId?: string
+  name?: string
+  delta?: string
+  content?: string
+  outcome?: {
+    type: string
+    interrupts?: Array<{ id: string; metadata?: Record<string, any> }>
+  }
+}
+
+const sse = (text: string): Array<Chunk> =>
+  text
+    .split('\n\n')
+    .filter((block) => block.startsWith('data: '))
+    .map((block) => JSON.parse(block.slice('data: '.length)))
+
+const textOf = (chunks: Array<Chunk>) =>
+  chunks
+    .filter((chunk) => chunk.type === 'TEXT_MESSAGE_CONTENT')
+    .map((chunk) => chunk.delta)
+    .join('')
+
+const toolResults = (chunks: Array<Chunk>) =>
+  chunks
+    .filter((chunk) => chunk.type === 'TOOL_CALL_RESULT')
+    .map((chunk) => chunk.content)
+
+/** The interrupt that `RUN_FINISHED` stops the turn for. */
+const interruptOf = (chunks: Array<Chunk>) => {
+  const finished = chunks.find((chunk) => chunk.type === 'RUN_FINISHED')
+  const interrupt = finished?.outcome?.interrupts?.[0]
+  if (!interrupt) throw new Error('The turn did not stop for an approval.')
+  return interrupt
+}
+
+type Snapshot = {
+  pendingQuestions: Array<{ questionId: string; message: string }>
+  waitingInputs: Array<{ inputId: string; delivery: string }>
+}
+
+type JournalEntry = {
+  headers?: Record<string, string>
+  body: { messages?: Array<{ role: string; content: unknown }> } | null
+}
+
+/**
+ * The custom events of a session stream, from its start. It reads until
+ * `isDone` is true for the events so far.
+ */
+async function customEvents(
+  url: string,
+  headers: Record<string, string>,
+  isDone: (events: Array<{ name?: string; value?: unknown }>) => boolean,
+) {
+  const response = await fetch(url, { headers })
+  if (!response.body) throw new Error('The session stream has no body.')
+  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader()
+  const events: Array<{ name?: string; value?: unknown }> = []
+  let buffer = ''
+  while (!isDone(events)) {
+    const read = await reader.read()
+    if (read.done) break
+    buffer += read.value
+    const blocks = buffer.split('\n\n')
+    buffer = blocks.pop() ?? ''
+    for (const block of blocks) {
+      // Each event has an `id:` line before its `data:` line.
+      const data = block.split('\n').find((line) => line.startsWith('data: '))
+      if (!data) continue
+      const frame: {
+        event?: { type: string; name?: string; value?: unknown }
+      } = JSON.parse(data.slice('data: '.length))
+      if (frame.event?.type === 'CUSTOM') {
+        events.push({ name: frame.event.name, value: frame.event.value })
+      }
+    }
+  }
+  await reader.cancel()
+  return events
+}
+
+/** One user of the harness protocol route: its headers and its requests. */
+function asUser(
+  request: APIRequestContext,
+  testId: string,
+  aimockPort: number,
+  token = 'e2e-token',
+  extraHeaders: Record<string, string> = {},
+) {
+  const headers = {
+    authorization: `Bearer ${token}`,
+    'x-test-id': testId,
+    'x-aimock-port': String(aimockPort),
+    ...extraHeaders,
+  }
+  const json = { ...headers, 'content-type': 'application/json' }
+  const run = (body: object) =>
+    request.post('/api/harness-protocol/run', {
+      headers: json,
+      data: { messages: [], tools: [], context: [], state: {}, ...body },
+    })
+  const control = async (threadId: string, input: unknown) =>
+    (
+      await request.post('/api/harness-protocol/control', {
+        headers: json,
+        data: { threadId, input },
+      })
+    ).json()
+  const read = async (route: string, threadId: string) =>
+    (
+      await request.get(`/api/harness-protocol/${route}?threadId=${threadId}`, {
+        headers,
+      })
+    ).json()
+  const transcript = (
+    threadId: string,
+  ): Promise<Array<{ id?: string; role: string; content: unknown }>> =>
+    read('transcript', threadId)
+  const answers = async (threadId: string) =>
+    (await transcript(threadId))
+      .filter((message) => message.role === 'assistant')
+      .map((message) => message.content)
+  const snapshot = (threadId: string): Promise<Snapshot> =>
+    read('snapshot', threadId)
+  /** The question that the thread waits for, or `undefined`. */
+  const question = async (threadId: string) =>
+    (await snapshot(threadId)).pendingQuestions[0]
+  return {
+    headers,
+    json,
+    run,
+    control,
+    transcript,
+    answers,
+    snapshot,
+    question,
+  }
+}
+
+const userMessage = (content: string) => [{ id: 'u1', role: 'user', content }]
+
+test.describe('harness protocol inputs', () => {
+  test('answers an approval on POST run with the run id the client sent', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort)
+    const threadId = `runid-${testId}`
+    const runId = `client-run-${testId}`
+    const body = {
+      threadId,
+      runId,
+      messages: userMessage('[harness-runid] deploy prod'),
+      forwardedProps: {},
+    }
+
+    const first = sse(await (await user.run(body)).text())
+    expect(first.find((chunk) => chunk.type === 'RUN_STARTED')?.runId).toBe(
+      runId,
+    )
+    const interrupt = interruptOf(first)
+    // A client matches the interrupt against the run id it sent.
+    expect(
+      interrupt.metadata?.['tanstack:interruptBinding']?.interruptedRunId,
+    ).toBe(runId)
+
+    // The same request again runs nothing: the model is not called again.
+    const retry = await user.run(body)
+    expect(retry.status()).toBe(200)
+    expect(await retry.text()).not.toContain('Deployed to prod.')
+
+    // A ChatClient with `persistence` reads this when the page loads.
+    const hydrate = await (
+      await request.get(`/api/harness-protocol/run?threadId=${threadId}`, {
+        headers: user.headers,
+      })
+    ).json()
+    expect(
+      hydrate.messages.map((message: { role: string }) => message.role),
+    ).toEqual(['user', 'assistant'])
+    expect(hydrate.interrupts).toMatchObject({
+      runId,
+      pending: [{ id: interrupt.id }],
+    })
+
+    const resumed = sse(
+      await (
+        await user.run({
+          threadId,
+          runId: `${runId}-resume`,
+          parentRunId: runId,
+          forwardedProps: {},
+          resume: [
+            {
+              interruptId: interrupt.id,
+              status: 'resolved',
+              payload: { approved: true },
+            },
+          ],
+        })
+      ).text(),
+    )
+    expect(resumed.find((chunk) => chunk.type === 'RUN_STARTED')?.runId).toBe(
+      `${runId}-resume`,
+    )
+    expect(toolResults(resumed).join('')).toContain('prod')
+    expect(textOf(resumed)).toBe('Deployed to prod.')
+  })
+
+  test('accepts a resolve sent as soon as RUN_FINISHED arrives', async ({
+    request,
+    baseURL,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort)
+    const threadId = `fast-resolve-${testId}`
+    // Read the stream as it arrives, and answer on RUN_FINISHED.
+    const response = await fetch(`${baseURL}/api/harness-protocol/run`, {
+      method: 'POST',
+      headers: user.json,
+      body: JSON.stringify({
+        threadId,
+        runId: `fast-${testId}`,
+        messages: userMessage('[harness-fast-resolve] deploy stage'),
+        tools: [],
+        context: [],
+        state: {},
+        forwardedProps: {},
+      }),
+    })
+    if (!response.body) throw new Error('POST run has no stream.')
+    const reader = response.body
+      .pipeThrough(new TextDecoderStream())
+      .getReader()
+    let buffer = ''
+    let receipt: unknown
+    while (receipt === undefined) {
+      const read = await reader.read()
+      if (read.done) break
+      buffer += read.value
+      let end = buffer.indexOf('\n\n')
+      while (end !== -1 && receipt === undefined) {
+        const block = buffer.slice(0, end)
+        buffer = buffer.slice(end + 2)
+        end = buffer.indexOf('\n\n')
+        if (!block.startsWith('data: ')) continue
+        const chunk: Chunk = JSON.parse(block.slice('data: '.length))
+        if (chunk.type !== 'RUN_FINISHED') continue
+        receipt = await user.control(threadId, {
+          op: 'resolve',
+          resume: [
+            {
+              interruptId: interruptOf([chunk]).id,
+              status: 'resolved',
+              payload: { approved: true },
+            },
+          ],
+        })
+      }
+    }
+    await reader.cancel()
+
+    expect(receipt).toMatchObject({ status: 'accepted' })
+    await expect
+      .poll(() => user.answers(threadId))
+      .toContain('Deployed to stage.')
+  })
+
+  test('gives forwardedProps to the tools as the input context', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort)
+    const chunks = sse(
+      await (
+        await user.run({
+          threadId: `context-${testId}`,
+          runId: `context-run-${testId}`,
+          messages: userMessage('[harness-context] probe'),
+          forwardedProps: { screen: 'settings' },
+        })
+      ).text(),
+    )
+    expect(toolResults(chunks).join('')).toContain('"screen":"settings"')
+    expect(textOf(chunks)).toBe('Probed the context.')
+  })
+
+  test('runs each input as the user who sent it', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const threadId = `sender-${testId}`
+    const opener = asUser(request, testId, aimockPort)
+    const bob = asUser(request, testId, aimockPort, 'e2e-token-bob')
+    // The first user opens the session of the thread.
+    const snapshot = await request.get(
+      `/api/harness-protocol/snapshot?threadId=${threadId}`,
+      { headers: opener.headers },
+    )
+    expect(snapshot.status()).toBe(200)
+
+    const chunks = sse(
+      await (
+        await bob.run({
+          threadId,
+          runId: `sender-run-${testId}`,
+          messages: userMessage('[harness-sender] who am i'),
+          forwardedProps: {},
+        })
+      ).text(),
+    )
+    expect(toolResults(chunks).join('')).toContain('"id":"bob"')
+    expect(textOf(chunks)).toBe('You are the sender.')
+  })
+
+  test('lets a ChatClient answer an approval on POST run', async ({
+    baseURL,
+    testId,
+    aimockPort,
+  }) => {
+    const client = new ChatClient({
+      connection: fetchServerSentEvents(`${baseURL}/api/harness-protocol/run`, {
+        headers: {
+          authorization: 'Bearer e2e-token',
+          'x-test-id': testId,
+          'x-aimock-port': String(aimockPort),
+        },
+      }),
+      threadId: `chatclient-${testId}`,
+      tools: [deploy.client()],
+    })
+    const assistantText = () =>
+      client
+        .getMessages()
+        .filter((message) => message.role === 'assistant')
+        .flatMap((message) => message.parts)
+        .flatMap((part) => (part.type === 'text' ? [part.content] : []))
+        .join('')
+
+    await client.sendMessage('[harness-chatclient] deploy dev')
+    const [interrupt] = client.getInterrupts()
+    expect(interrupt).toMatchObject({ canResolve: true })
+
+    client.resolveInterrupts(true)
+    await expect.poll(assistantText).toContain('Deployed to dev.')
+    client.dispose()
+  })
+
+  test('lets a reloaded ChatClient join the turn that still runs', async ({
+    request,
+    baseURL,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort)
+    const threadId = `rejoin-${testId}`
+    const connection = () =>
+      fetchServerSentEvents(`${baseURL}/api/harness-protocol/run`, {
+        headers: user.headers,
+      })
+    /** Each message as its role and its text, to compare two clients. */
+    const shape = (client: ChatClient) =>
+      client.getMessages().map((message) => ({
+        role: message.role,
+        text: message.parts
+          .flatMap((part) => (part.type === 'text' ? [part.content] : []))
+          .join(''),
+      }))
+    const pendingQuestion = async () => {
+      const snapshot: { pendingQuestions: Array<{ questionId: string }> } =
+        await (
+          await request.get(
+            `/api/harness-protocol/snapshot?threadId=${threadId}`,
+            { headers: user.headers },
+          )
+        ).json()
+      return snapshot.pendingQuestions[0]?.questionId
+    }
+
+    // The first tab starts a turn. Its tool waits for an answer.
+    const first = new ChatClient({ connection: connection(), threadId })
+    const sent = first.sendMessage('[harness-rejoin] ask my name')
+    await expect.poll(pendingQuestion).toBeTruthy()
+
+    // The page reloads: a new client loads the thread from the server and
+    // joins the turn that still runs.
+    const reloaded = new ChatClient({
+      connection: connection(),
+      threadId,
+      persistence: true,
+    })
+    reloaded.attach()
+    await expect
+      .poll(() => reloaded.getMessages().map((message) => message.role))
+      .toEqual(['user', 'assistant'])
+
+    expect(
+      await user.control(threadId, {
+        op: 'answer',
+        questionId: await pendingQuestion(),
+        value: 'Otto',
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    await sent
+    await expect.poll(() => shape(reloaded).at(-1)?.text).toBe('Hello, Otto.')
+    // The joined client shows the same messages as the tab that sent it.
+    expect(shape(reloaded)).toEqual(shape(first))
+    first.dispose()
+    reloaded.dispose()
+  })
+
+  test('cancels one waiting input and moves another into the running turn', async ({
+    request,
+    baseURL,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort)
+    const threadId = `waiting-${testId}`
+    const dropped = `drop-${testId}`
+    const moved = `move-${testId}`
+    // The turn waits for an answer, so the next inputs wait too.
+    expect(
+      await user.control(threadId, {
+        op: 'prompt',
+        message: '[harness-queue] ask my name',
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    await expect.poll(() => user.question(threadId)).toBeTruthy()
+    for (const [inputId, message] of [
+      [dropped, '[harness-queue-dropped] never runs'],
+      [moved, '[harness-queue-moved] say it now'],
+    ]) {
+      expect(
+        await user.control(threadId, { op: 'followUp', message, inputId }),
+      ).toMatchObject({ status: 'queued' })
+    }
+    expect((await user.snapshot(threadId)).waitingInputs).toMatchObject([
+      { inputId: dropped, delivery: 'queue' },
+      { inputId: moved, delivery: 'queue' },
+    ])
+
+    expect(
+      await user.control(threadId, { op: 'cancelInput', inputId: dropped }),
+    ).toMatchObject({ status: 'accepted' })
+    // A cancelled input does not wait any more.
+    expect(
+      await user.control(threadId, { op: 'cancelInput', inputId: dropped }),
+    ).toMatchObject({ status: 'rejected', reason: 'not_waiting' })
+    expect(
+      await user.control(threadId, {
+        op: 'setDelivery',
+        inputId: moved,
+        delivery: 'steer',
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    expect((await user.snapshot(threadId)).waitingInputs).toMatchObject([
+      { inputId: moved, delivery: 'steer' },
+    ])
+
+    // The session stream tells every client about both changes.
+    const events = await customEvents(
+      `${baseURL}/api/harness-protocol/events?threadId=${threadId}&from=0`,
+      user.headers,
+      (seen) => seen.some((event) => event.name === 'harness.input.delivery'),
+    )
+    expect(events).toContainEqual({
+      name: 'harness.input.settled',
+      value: expect.objectContaining({ inputId: dropped, outcome: 'aborted' }),
+    })
+    expect(events).toContainEqual({
+      name: 'harness.input.delivery',
+      value: { inputId: moved, delivery: 'steer' },
+    })
+
+    // After the answer, the moved input joins the next model call.
+    const asked = await user.question(threadId)
+    expect(
+      await user.control(threadId, {
+        op: 'answer',
+        questionId: asked?.questionId,
+        value: 'Otto',
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    await expect
+      .poll(() => user.answers(threadId))
+      .toContain('Hello, Otto. I got the moved message.')
+    const sent = (await user.transcript(threadId))
+      .filter((message) => message.role === 'user')
+      .map((message) => message.content)
+    expect(sent).toEqual([
+      '[harness-queue] ask my name',
+      '[harness-queue-moved] say it now',
+    ])
+  })
+
+  test('moves a running tool call to the background', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort)
+    const threadId = `background-${testId}`
+    // Before the tool runs, there is nothing to move.
+    expect(await user.control(threadId, { op: 'background' })).toMatchObject({
+      status: 'rejected',
+      reason: 'not_running',
+    })
+    expect(
+      await user.control(threadId, {
+        op: 'prompt',
+        message: '[harness-background] build it',
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    // `slowBuild` waits for `release`. A client needs no `expose` entry.
+    await expect
+      .poll(
+        async () => (await user.control(threadId, { op: 'background' })).status,
+      )
+      .toBe('accepted')
+
+    // The tool call answers at once, and the turn ends.
+    await expect
+      .poll(() => user.answers(threadId))
+      .toContain('The build runs in the background.')
+    const results = (await user.transcript(threadId))
+      .filter((message) => message.role === 'tool')
+      .map((message) => message.content)
+    expect(String(results[0])).toContain('The job moved to the background.')
+
+    // When the job ends, a note wakes the session.
+    expect(
+      await user.control(threadId, { op: 'command', name: 'release' }),
+    ).toMatchObject({ status: 'accepted' })
+    await expect
+      .poll(() => user.answers(threadId))
+      .toContain('The build is done.')
+  })
+
+  test('asks an MCP elicitation as a question and sends the answer to the server', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort, 'e2e-token', {
+      'x-harness-mcp': '1',
+    })
+    const threadId = `elicit-${testId}`
+    expect(
+      await user.control(threadId, {
+        op: 'prompt',
+        message: '[harness-elicit] what is the forecast',
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    await expect.poll(() => user.question(threadId)).toBeTruthy()
+    const asked = await user.question(threadId)
+    expect(asked).toMatchObject({
+      message: 'Which city?',
+      schema: { type: 'object', properties: { value: { type: 'string' } } },
+    })
+
+    expect(
+      await user.control(threadId, {
+        op: 'answer',
+        questionId: asked?.questionId,
+        value: { value: 'Paris' },
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    await expect
+      .poll(() => user.answers(threadId))
+      .toContain('The forecast for Paris is sunny.')
+
+    // The server got the answer: the tool result has the city.
+    const result = (await user.transcript(threadId)).find(
+      (message) => message.role === 'tool',
+    )
+    expect(JSON.stringify(result?.content)).toContain('Forecast for Paris')
+  })
+
+  test('asks each elicitation/create request of a spec 2025 server, two in one tool call', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort, 'e2e-token', {
+      'x-harness-mcp': '2025',
+    })
+    const threadId = `elicit-2025-${testId}`
+    expect(
+      await user.control(threadId, {
+        op: 'prompt',
+        message: '[harness-elicit-2025] book a trip',
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    for (const [message, value] of [
+      ['Which city?', 'Paris'],
+      ['Which seat?', '12A'],
+    ]) {
+      await expect
+        .poll(async () => (await user.question(threadId))?.message)
+        .toBe(message)
+      const asked = await user.question(threadId)
+      expect(
+        await user.control(threadId, {
+          op: 'answer',
+          questionId: asked?.questionId,
+          value: { value },
+        }),
+      ).toMatchObject({ status: 'accepted' })
+    }
+    await expect
+      .poll(() => user.answers(threadId))
+      .toContain('Your trip to Paris is booked, seat 12A.')
+
+    // The server got both answers in the same tool call.
+    const result = (await user.transcript(threadId)).find(
+      (message) => message.role === 'tool',
+    )
+    expect(JSON.stringify(result?.content)).toContain('Booked Paris, seat 12A')
+  })
+
+  test('answers the stored user message on continue, with no new message', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort)
+    const threadId = `continue-${testId}`
+    expect(
+      await user.control(threadId, {
+        op: 'prompt',
+        message: '[harness-continue] name a color',
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    await expect.poll(() => user.answers(threadId)).toEqual(['Red.'])
+    // A fork through the prompt ends with the user message.
+    const at = (await user.transcript(threadId))[0]?.id
+    if (!at) throw new Error('The prompt has no message id.')
+    const forked = await request.post('/api/harness-protocol/sessions', {
+      headers: user.json,
+      data: { op: 'fork', threadId, through: at },
+    })
+    const fork: { threadId: string } = await forked.json()
+
+    expect(await user.control(fork.threadId, { op: 'continue' })).toMatchObject(
+      { status: 'accepted' },
+    )
+    await expect
+      .poll(async () =>
+        (await user.transcript(fork.threadId)).map(
+          (message) => `${message.role}: ${String(message.content)}`,
+        ),
+      )
+      .toEqual(['user: [harness-continue] name a color', 'assistant: Blue.'])
+  })
+
+  test('gives the model the ephemeral messages of a prompt, and never stores them', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort)
+    const threadId = `ephemeral-prompt-${testId}`
+    const message = '[harness-ephemeral-prompt] name a fruit'
+    const note = '[harness-ephemeral-prompt] note: answer in one word'
+    expect(
+      await user.control(threadId, {
+        op: 'prompt',
+        message,
+        ephemeral: [{ role: 'user', content: note }],
+      }),
+    ).toMatchObject({ status: 'accepted' })
+
+    // The fixture answers only when the note is the last user message.
+    await expect.poll(() => user.answers(threadId)).toEqual(['Apple.'])
+    expect(JSON.stringify(await user.transcript(threadId))).not.toContain(note)
+    const journal = await request.get(
+      `http://127.0.0.1:${aimockPort}/v1/_requests`,
+    )
+    const entries: Array<JournalEntry> = await journal.json()
+    const sent = entries
+      .filter((entry) => entry.headers?.['x-test-id'] === testId)
+      .at(-1)
+      ?.body?.messages?.slice(-2)
+      .map((sentMessage) => sentMessage.content)
+    expect(sent).toEqual([message, note])
+  })
+
+  test('gives the model the ephemeral messages of continue, and never stores them', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort)
+    const threadId = `ephemeral-continue-${testId}`
+    const note = '[harness-ephemeral-continue] note: pick another color'
+    expect(
+      await user.control(threadId, {
+        op: 'prompt',
+        message: '[harness-ephemeral-continue] name a color',
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    await expect.poll(() => user.answers(threadId)).toEqual(['Red.'])
+    // A fork through the prompt ends with the user message.
+    const at = (await user.transcript(threadId))[0]?.id
+    if (!at) throw new Error('The prompt has no message id.')
+    const forked = await request.post('/api/harness-protocol/sessions', {
+      headers: user.json,
+      data: { op: 'fork', threadId, through: at },
+    })
+    const fork: { threadId: string } = await forked.json()
+
+    expect(
+      await user.control(fork.threadId, {
+        op: 'continue',
+        ephemeral: [{ role: 'user', content: note }],
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    // The fixture answers only when the note is the last user message.
+    await expect
+      .poll(async () =>
+        (await user.transcript(fork.threadId)).map(
+          (message) => `${message.role}: ${String(message.content)}`,
+        ),
+      )
+      .toEqual([
+        'user: [harness-ephemeral-continue] name a color',
+        'assistant: Green.',
+      ])
+  })
+
+  test('rejects continue on an empty thread with nothing_to_continue', async ({
+    request,
+    baseURL,
+    testId,
+    aimockPort,
+  }) => {
+    const user = asUser(request, testId, aimockPort)
+    const threadId = `continue-empty-${testId}`
+    const inputId = `empty-${testId}`
+    await user.control(threadId, { op: 'continue', inputId })
+
+    // The session checks the transcript when the turn starts, and tells
+    // every client.
+    const events = await customEvents(
+      `${baseURL}/api/harness-protocol/events?threadId=${threadId}&from=0`,
+      user.headers,
+      (seen) => seen.some((event) => event.name === 'harness.input.rejected'),
+    )
+    expect(events).toContainEqual({
+      name: 'harness.input.rejected',
+      value: { inputId, reason: 'nothing_to_continue' },
+    })
+    expect(await user.transcript(threadId)).toEqual([])
+  })
+})
diff --git a/testing/e2e/tests/harness-protocol.spec.ts b/testing/e2e/tests/harness-protocol.spec.ts
new file mode 100644
index 0000000000..a815485660
--- /dev/null
+++ b/testing/e2e/tests/harness-protocol.spec.ts
@@ -0,0 +1,596 @@
+import { test, expect } from './fixtures'
+
+test.describe('harness protocol', () => {
+  const headers = (testId: string, aimockPort: number) => ({
+    authorization: 'Bearer e2e-token',
+    'x-test-id': testId,
+    'x-aimock-port': String(aimockPort),
+  })
+
+  test('refuses a request without the token', async ({ request }) => {
+    const response = await request.get('/api/harness-protocol/capabilities')
+    expect(response.status()).toBe(401)
+  })
+
+  test('lists exposed agents in the capabilities', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.get('/api/harness-protocol/capabilities', {
+      headers: headers(testId, aimockPort),
+    })
+    const body = await response.json()
+    expect(body.identity.name).toBe('e2e/protocol')
+    expect(body.custom.tanstack.agents[0].name).toBe('echo')
+  })
+
+  test('streams a standard AG-UI run through a session', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-protocol/run', {
+      headers: {
+        ...headers(testId, aimockPort),
+        'content-type': 'application/json',
+      },
+      data: {
+        threadId: `protocol-${testId}`,
+        // The run id is also the input id, so each test needs its own.
+        runId: `client-run-${testId}`,
+        messages: [
+          { id: 'u1', role: 'user', content: '[harness-protocol] hello' },
+        ],
+        tools: [],
+        context: [],
+        state: {},
+        forwardedProps: {},
+      },
+    })
+    expect(response.headers()['content-type']).toContain('text/event-stream')
+    const text = await response.text()
+    const events = text
+      .split('\n')
+      .filter((line) => line.startsWith('data: '))
+      .map((line) => JSON.parse(line.slice(6)))
+    const answer = events
+      .filter((event) => event.type === 'TEXT_MESSAGE_CONTENT')
+      .map((event) => event.delta)
+      .join('')
+    expect(answer).toBe('Hello over the harness protocol.')
+    // The turn runs as the run id the client sent.
+    expect(events.find((event) => event.type === 'RUN_STARTED').runId).toBe(
+      `client-run-${testId}`,
+    )
+    expect(events.at(-1).name).toBe('harness.operation.finished')
+  })
+
+  test('changes a plugin setting and runs a plugin command', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const control = async (input: unknown) =>
+      (
+        await request.post('/api/harness-protocol/control', {
+          headers: {
+            ...headers(testId, aimockPort),
+            'content-type': 'application/json',
+          },
+          data: { threadId: `plugins-${testId}`, input },
+        })
+      ).json()
+
+    expect(
+      await control({ op: 'config', key: 'tone', value: 'warm' }),
+    ).toMatchObject({
+      status: 'accepted',
+    })
+    const rejected = await control({ op: 'config', key: 'tone', value: 'loud' })
+    expect(rejected.status).toBe('rejected')
+    expect(rejected.reason).toContain('plain, warm')
+    const command = await control({ op: 'command', name: 'greet' })
+    expect(command.status).toBe('accepted')
+    expect(command.operationId).toMatch(/^op-command-/)
+  })
+
+  test('refuses a command and a config key that the harness does not expose', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const control = async (input: unknown) =>
+      (
+        await request.post('/api/harness-protocol/control', {
+          headers: {
+            ...headers(testId, aimockPort),
+            'content-type': 'application/json',
+          },
+          data: { threadId: `expose-${testId}`, input },
+        })
+      ).json()
+
+    expect(
+      await control({ op: 'command', name: 'mode', input: 'bypass' }),
+    ).toMatchObject({ status: 'rejected', reason: 'not_exposed' })
+    expect(
+      await control({ op: 'config', key: 'mode', value: 'bypass' }),
+    ).toMatchObject({ status: 'rejected', reason: 'not_exposed' })
+  })
+
+  test('runs a retried prompt with the same inputId once on a durable host', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const threadId = `durable-${testId}`
+    const durable = { ...headers(testId, aimockPort), 'x-harness-durable': '1' }
+    const control = async (input: unknown) =>
+      (
+        await request.post('/api/harness-protocol/control', {
+          headers: { ...durable, 'content-type': 'application/json' },
+          data: { threadId, input },
+        })
+      ).json()
+    const prompt = {
+      op: 'prompt',
+      message: '[harness-durable] run once',
+      inputId: `once-${testId}`,
+    }
+
+    const first = await control(prompt)
+    const retry = await control(prompt)
+
+    expect(first.status).toBe('accepted')
+    expect(retry).toEqual(first)
+    const answers = async () => {
+      const response = await request.get(
+        `/api/harness-protocol/transcript?threadId=${threadId}`,
+        { headers: durable },
+      )
+      const transcript: Array<{ role: string; content: unknown }> =
+        await response.json()
+      return transcript
+        .filter((message) => message.role === 'assistant')
+        .map((message) => message.content)
+    }
+    await expect.poll(answers).toEqual(['Stored once.'])
+    expect(
+      await control({ ...prompt, message: '[harness-durable] other text' }),
+    ).toMatchObject({ status: 'rejected', reason: 'conflict' })
+  })
+
+  test('retries a 503 from the model in the same turn', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const threadId = `retry-${testId}`
+    const turnHeaders = {
+      ...headers(testId, aimockPort),
+      'x-harness-turn': 'retry',
+    }
+    const receipt = await (
+      await request.post('/api/harness-protocol/control', {
+        headers: { ...turnHeaders, 'content-type': 'application/json' },
+        data: {
+          threadId,
+          input: { op: 'prompt', message: '[harness-retry] try twice' },
+        },
+      })
+    ).json()
+    expect(receipt.status).toBe('accepted')
+
+    const answers = async () => {
+      const response = await request.get(
+        `/api/harness-protocol/transcript?threadId=${threadId}`,
+        { headers: turnHeaders },
+      )
+      const transcript: Array<{ role: string; content: unknown }> =
+        await response.json()
+      return transcript
+        .filter((message) => message.role === 'assistant')
+        .map((message) => message.content)
+    }
+    await expect.poll(answers).toEqual(['Back after a retry.'])
+  })
+
+  test('sends the model back to work with beforeFinish', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const threadId = `finish-${testId}`
+    const turnHeaders = {
+      ...headers(testId, aimockPort),
+      'x-harness-turn': 'finish',
+    }
+    await request.post('/api/harness-protocol/control', {
+      headers: { ...turnHeaders, 'content-type': 'application/json' },
+      data: {
+        threadId,
+        input: { op: 'prompt', message: '[harness-finish] post it' },
+      },
+    })
+
+    const transcript = async () => {
+      const response = await request.get(
+        `/api/harness-protocol/transcript?threadId=${threadId}`,
+        { headers: turnHeaders },
+      )
+      const messages: Array<{ role: string; content: unknown }> =
+        await response.json()
+      return messages.map(
+        (message) => `${message.role}: ${String(message.content)}`,
+      )
+    }
+    await expect
+      .poll(transcript)
+      .toEqual([
+        'user: [harness-finish] post it',
+        'assistant: Draft answer.',
+        'user: [harness-finish] reminder: post the answer',
+        'assistant: Posted answer.',
+      ])
+  })
+
+  test('reverts to an earlier message, then unreverts', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const threadId = `revert-${testId}`
+    const json = {
+      ...headers(testId, aimockPort),
+      'content-type': 'application/json',
+    }
+    const control = async (input: unknown) =>
+      (
+        await request.post('/api/harness-protocol/control', {
+          headers: json,
+          data: { threadId, input },
+        })
+      ).json()
+    const transcript = async () => {
+      const response = await request.get(
+        `/api/harness-protocol/transcript?threadId=${threadId}`,
+        { headers: json },
+      )
+      const messages: Array<{ id: string; role: string; content: unknown }> =
+        await response.json()
+      return messages
+    }
+    const lines = async () =>
+      (await transcript()).map(
+        (message) => `${message.role}: ${String(message.content)}`,
+      )
+    await control({ op: 'prompt', message: '[harness-revert] first' })
+    await expect.poll(lines).toHaveLength(2)
+    await control({ op: 'prompt', message: '[harness-revert] second' })
+    const all = [
+      'user: [harness-revert] first',
+      'assistant: First answer.',
+      'user: [harness-revert] second',
+      'assistant: Second answer.',
+    ]
+    await expect.poll(lines).toEqual(all)
+    const [, firstAnswer] = await transcript()
+
+    // A refused revert changes nothing, so the test can ask again until the
+    // last turn has ended.
+    await expect
+      .poll(
+        async () =>
+          (await control({ op: 'revert', messageId: firstAnswer?.id })).status,
+      )
+      .toBe('accepted')
+    expect(await lines()).toEqual(all.slice(0, 2))
+
+    expect(await control({ op: 'unrevert' })).toMatchObject({
+      status: 'accepted',
+    })
+    expect(await lines()).toEqual(all)
+  })
+
+  test('gives an ephemeral reminder from beforeFinish to the next model call only', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const threadId = `ephemeral-${testId}`
+    const turnHeaders = {
+      ...headers(testId, aimockPort),
+      'x-harness-turn': 'ephemeral',
+    }
+    await request.post('/api/harness-protocol/control', {
+      headers: { ...turnHeaders, 'content-type': 'application/json' },
+      data: {
+        threadId,
+        input: { op: 'prompt', message: '[harness-finish] post it' },
+      },
+    })
+
+    const transcript = async () => {
+      const response = await request.get(
+        `/api/harness-protocol/transcript?threadId=${threadId}`,
+        { headers: turnHeaders },
+      )
+      const messages: Array<{ role: string; content: unknown }> =
+        await response.json()
+      return messages.map(
+        (message) => `${message.role}: ${String(message.content)}`,
+      )
+    }
+    // The transcript does not keep the reminder.
+    await expect
+      .poll(transcript)
+      .toEqual([
+        'user: [harness-finish] post it',
+        'assistant: Draft answer.',
+        'assistant: Posted answer.',
+      ])
+
+    // The second model call got the reminder as its last message.
+    const journal = await request.get(
+      `http://127.0.0.1:${aimockPort}/v1/_requests`,
+    )
+    const entries: Array<{
+      headers?: Record<string, string>
+      body: { messages?: Array<{ role: string; content: unknown }> } | null
+    }> = await journal.json()
+    const lastSent = entries
+      .filter((entry) => entry.headers?.['x-test-id'] === testId)
+      .map((entry) => entry.body?.messages?.at(-1)?.content)
+    expect(lastSent).toEqual([
+      '[harness-finish] post it',
+      '[harness-finish] reminder: post the answer',
+    ])
+  })
+
+  test('takes a control input and returns a receipt', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const response = await request.post('/api/harness-protocol/control', {
+      headers: {
+        ...headers(testId, aimockPort),
+        'content-type': 'application/json',
+      },
+      data: {
+        threadId: `control-${testId}`,
+        input: { op: 'agent', agent: 'echo', input: { text: 'hi' } },
+      },
+    })
+    const receipt = await response.json()
+    expect(receipt.status).toBe('accepted')
+    expect(receipt.operationId).toMatch(/^op-agent-/)
+  })
+
+  test('lists, renames, and forks sessions with their settings', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const auth = headers(testId, aimockPort)
+    const json = { ...auth, 'content-type': 'application/json' }
+    const first = `sessions-a-${testId}`
+    const second = `sessions-b-${testId}`
+    const settings = { model: 'strong', instructions: 'Answer in one word.' }
+    const configured = await request.post('/api/harness-protocol/control', {
+      headers: json,
+      data: { threadId: first, input: { op: 'configure', settings } },
+    })
+    expect(await configured.json()).toMatchObject({ status: 'accepted' })
+    const run = await request.post('/api/harness-protocol/run', {
+      headers: json,
+      data: {
+        threadId: first,
+        runId: `sessions-run-${testId}`,
+        messages: [
+          { id: 'u1', role: 'user', content: '[harness-protocol] hello' },
+        ],
+        tools: [],
+        context: [],
+        state: {},
+        forwardedProps: {},
+      },
+    })
+    // The stream ends with the turn.
+    await run.text()
+    // The second thread only opens.
+    const opened = await request.get(
+      `/api/harness-protocol/snapshot?threadId=${second}`,
+      { headers: auth },
+    )
+    expect(opened.status()).toBe(200)
+
+    const sessions = (body: object) =>
+      request.post('/api/harness-protocol/sessions', {
+        headers: json,
+        data: body,
+      })
+    const title = 'Trip plan'
+    const renamed = await sessions({ op: 'rename', threadId: first, title })
+    expect(await renamed.json()).toMatchObject({ threadId: first, title })
+
+    const transcript = async (threadId: string) => {
+      const response = await request.get(
+        `/api/harness-protocol/transcript?threadId=${threadId}`,
+        { headers: auth },
+      )
+      const messages: Array<{ id?: string; role: string; content: unknown }> =
+        await response.json()
+      return messages
+    }
+    const source = await transcript(first)
+    expect(source.map((message) => message.role)).toEqual(['user', 'assistant'])
+    const at = source[0]?.id
+    if (!at) throw new Error('The prompt has no message id.')
+    const forked = await sessions({ op: 'fork', threadId: first, through: at })
+    expect(forked.status()).toBe(200)
+    const fork: { threadId: string; title?: string } = await forked.json()
+    expect(fork.title).toBe(`${title} (fork)`)
+    // The fork has the messages through the prompt, and the stored settings.
+    const copied = await transcript(fork.threadId)
+    expect(copied.map((message) => message.content)).toEqual([
+      '[harness-protocol] hello',
+    ])
+    const described = await request.get(
+      `/api/harness-protocol/describe?threadId=${fork.threadId}`,
+      { headers: auth },
+    )
+    expect((await described.json()).settings).toMatchObject(settings)
+
+    // The host is shared, so the list has the threads of other tests too.
+    const response = await request.get('/api/harness-protocol/sessions', {
+      headers: auth,
+    })
+    const listed: { entries: Array<{ threadId: string; title?: string }> } =
+      await response.json()
+    const titles = Object.fromEntries(
+      listed.entries.map((entry) => [entry.threadId, entry.title ?? null]),
+    )
+    expect(titles).toMatchObject({
+      [first]: title,
+      [second]: null,
+      [fork.threadId]: `${title} (fork)`,
+    })
+  })
+
+  test('lists the child of a thread with parentThreadId', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const auth = headers(testId, aimockPort)
+    const threadId = `children-${testId}`
+    const response = await request.post('/api/harness-protocol/control', {
+      headers: { ...auth, 'content-type': 'application/json' },
+      data: {
+        threadId,
+        input: { op: 'agent', agent: 'echo', input: { text: 'hi' } },
+      },
+    })
+    expect(await response.json()).toMatchObject({ status: 'accepted' })
+
+    // The agent run is a child session `subagent:<id>` of the thread.
+    const query = new URLSearchParams({ parentThreadId: threadId })
+    await expect
+      .poll(async () => {
+        const listed = await request.get(
+          `/api/harness-protocol/sessions?${query}`,
+          { headers: auth },
+        )
+        const body: {
+          entries: Array<{ threadId: string; parentThreadId?: string }>
+        } = await listed.json()
+        return body.entries
+      })
+      .toEqual([
+        expect.objectContaining({
+          threadId: expect.stringMatching(/^subagent:/),
+          parentThreadId: threadId,
+        }),
+      ])
+  })
+
+  test('searches the session list by title, without case', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const auth = headers(testId, aimockPort)
+    const json = { ...auth, 'content-type': 'application/json' }
+    const titles = {
+      [`search-a-${testId}`]: `Plan the trip ${testId}`,
+      [`search-b-${testId}`]: `Write the docs ${testId}`,
+      [`search-c-${testId}`]: `Trip budget ${testId}`,
+    }
+    for (const [threadId, title] of Object.entries(titles)) {
+      const opened = await request.get(
+        `/api/harness-protocol/snapshot?threadId=${threadId}`,
+        { headers: auth },
+      )
+      expect(opened.status()).toBe(200)
+      const renamed = await request.post('/api/harness-protocol/sessions', {
+        headers: json,
+        data: { op: 'rename', threadId, title },
+      })
+      expect(renamed.status()).toBe(200)
+    }
+
+    // The test id keeps out the threads of other tests on the shared host.
+    const query = new URLSearchParams({ search: `TRIP ${testId}` })
+    const response = await request.get(
+      `/api/harness-protocol/sessions?${query}`,
+      { headers: auth },
+    )
+    const listed: { entries: Array<{ threadId: string }> } =
+      await response.json()
+    expect(listed.entries.map((entry) => entry.threadId)).toEqual([
+      `search-a-${testId}`,
+    ])
+    const budget = await request.get(
+      `/api/harness-protocol/sessions?${new URLSearchParams({ search: 'trip' })}`,
+      { headers: auth },
+    )
+    const found: { entries: Array<{ threadId: string }> } = await budget.json()
+    expect(found.entries.map((entry) => entry.threadId)).toEqual(
+      expect.arrayContaining([`search-a-${testId}`, `search-c-${testId}`]),
+    )
+    expect(found.entries.map((entry) => entry.threadId)).not.toContain(
+      `search-b-${testId}`,
+    )
+  })
+
+  test('shows running, then idle, on the host status feed', async ({
+    request,
+    baseURL,
+    testId,
+    aimockPort,
+  }) => {
+    const auth = headers(testId, aimockPort)
+    const threadId = `status-${testId}`
+    // Open the session first, so the feed starts with its status.
+    await request.get(`/api/harness-protocol/snapshot?threadId=${threadId}`, {
+      headers: auth,
+    })
+    const feed = await fetch(`${baseURL}/api/harness-protocol/host-events`, {
+      headers: auth,
+    })
+    if (!feed.body) throw new Error('The status feed has no stream.')
+    const reader = feed.body.pipeThrough(new TextDecoderStream()).getReader()
+    // The feed has every session of this user. This test reads its own.
+    const statuses: Array<string> = []
+    let buffer = ''
+    while (statuses.length < 3) {
+      const read = await reader.read()
+      if (read.done) break
+      buffer += read.value
+      const blocks = buffer.split('\n\n')
+      buffer = blocks.pop() ?? ''
+      for (const block of blocks) {
+        if (!block.startsWith('data: ')) continue
+        const event: { type: string; threadId?: string; status?: string } =
+          JSON.parse(block.slice('data: '.length))
+        const isOurs = event.type === 'status' && event.threadId === threadId
+        if (!isOurs || !event.status) continue
+        statuses.push(event.status)
+        if (statuses.length > 1) continue
+        // The first status shows that the feed reads, so start a turn now.
+        const receipt = await request.post('/api/harness-protocol/control', {
+          headers: { ...auth, 'content-type': 'application/json' },
+          data: {
+            threadId,
+            input: { op: 'prompt', message: '[harness-protocol] hello' },
+          },
+        })
+        expect(await receipt.json()).toMatchObject({ status: 'accepted' })
+      }
+    }
+    await reader.cancel()
+    expect(statuses).toEqual(['idle', 'running', 'idle'])
+  })
+})
diff --git a/testing/e2e/tests/harness-thread-controls.spec.ts b/testing/e2e/tests/harness-thread-controls.spec.ts
new file mode 100644
index 0000000000..5e3534f9d2
--- /dev/null
+++ b/testing/e2e/tests/harness-thread-controls.spec.ts
@@ -0,0 +1,328 @@
+import { test, expect } from './fixtures'
+import type { APIRequestContext } from '@playwright/test'
+
+/**
+ * Per-thread controls of a harness session over HTTP: usage totals, stored
+ * settings (`configure`), `reset` with a handoff note, and `host.fork`
+ * (through a test-only route). The model is the OpenAI adapter against
+ * aimock, and aimock's journal shows what each model call sent.
+ */
+
+type JournalEntry = {
+  headers?: Record<string, string>
+  body: {
+    model?: string
+    messages?: Array<{ role: string; content: unknown }>
+  } | null
+}
+
+type Message = {
+  id?: string
+  role: string
+  content: unknown
+  metadata?: { harness?: { reset?: unknown } }
+}
+
+const textOf = (sse: string) =>
+  sse
+    .split('\n\n')
+    .filter((block) => block.startsWith('data: '))
+    .map((block) => JSON.parse(block.slice('data: '.length)))
+    .filter((chunk) => chunk.type === 'TEXT_MESSAGE_CONTENT')
+    .map((chunk) => chunk.delta)
+    .join('')
+
+/** The text of a message's content, for a string or a list of parts. */
+const contentText = (content: unknown) =>
+  typeof content === 'string'
+    ? content
+    : Array.isArray(content)
+      ? content
+          .map((part) =>
+            typeof part === 'object' && part !== null && 'text' in part
+              ? String(part.text)
+              : '',
+          )
+          .join('')
+      : ''
+
+function client(
+  request: APIRequestContext,
+  testId: string,
+  aimockPort: number,
+) {
+  const headers = {
+    authorization: 'Bearer e2e-token',
+    'x-test-id': testId,
+    'x-aimock-port': String(aimockPort),
+  }
+  const json = { ...headers, 'content-type': 'application/json' }
+  let runs = 0
+  const prompt = async (threadId: string, content: string) => {
+    runs += 1
+    const response = await request.post('/api/harness-protocol/run', {
+      headers: json,
+      data: {
+        threadId,
+        runId: `run-${testId}-${runs}`,
+        messages: [{ id: `u-${runs}`, role: 'user', content }],
+        tools: [],
+        context: [],
+        state: {},
+        forwardedProps: {},
+      },
+    })
+    expect(response.status()).toBe(200)
+    return textOf(await response.text())
+  }
+  const control = async (threadId: string, input: unknown) =>
+    (
+      await request.post('/api/harness-protocol/control', {
+        headers: json,
+        data: { threadId, input },
+      })
+    ).json()
+  const read = async (route: string, threadId: string) =>
+    (
+      await request.get(`/api/harness-protocol/${route}?threadId=${threadId}`, {
+        headers,
+      })
+    ).json()
+  /** This test's model calls, in order, from aimock's journal. */
+  const modelCalls = async () => {
+    const journal = await request.get(
+      `http://127.0.0.1:${aimockPort}/v1/_requests`,
+    )
+    const entries = (await journal.json()) as Array<JournalEntry>
+    return entries.filter((entry) => entry.headers?.['x-test-id'] === testId)
+  }
+  return { headers, json, prompt, control, read, modelCalls }
+}
+
+test.describe('harness thread controls', () => {
+  test('counts the usage of a turn per model and per sender', async ({
+    request,
+    testId,
+    aimockPort,
+    baseURL,
+  }) => {
+    const user = client(request, testId, aimockPort)
+    const threadId = `usage-${testId}`
+    expect(await user.prompt(threadId, '[harness-usage] hello')).toBe(
+      'Counted.',
+    )
+
+    const { usage } = await user.read('snapshot', threadId)
+    // aimock reports no token counts for this adapter, so the call count is
+    // what this test can check.
+    expect(usage.total.calls).toBeGreaterThanOrEqual(1)
+    expect(usage.bySender.e2e.calls).toBe(usage.total.calls)
+    expect(Object.keys(usage.byModel).join(' ')).toContain('gpt-4o')
+
+    // The session stream has a `harness.usage` event for a live total.
+    const events = await fetch(
+      `${baseURL}/api/harness-protocol/events?threadId=${threadId}&from=0`,
+      { headers: user.headers },
+    )
+    const reader = events.body!.pipeThrough(new TextDecoderStream()).getReader()
+    let feed = ''
+    while (!feed.includes('"harness.usage"')) {
+      const { value, done } = await reader.read()
+      if (done) break
+      feed += value
+    }
+    await reader.cancel()
+    expect(feed).toContain('"harness.usage"')
+  })
+
+  test('runs the next turn with the stored model and instructions', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = client(request, testId, aimockPort)
+    const threadId = `settings-${testId}`
+    expect(
+      await user.control(threadId, {
+        op: 'configure',
+        settings: { model: 'strong', instructions: 'Answer in one word.' },
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    expect(
+      await user.control(threadId, {
+        op: 'configure',
+        settings: { model: 'missing' },
+      }),
+    ).toMatchObject({ status: 'rejected' })
+    // The harness does not expose `plugins` to clients.
+    expect(
+      await user.control(threadId, {
+        op: 'configure',
+        settings: { plugins: { remove: ['e2e/settings'] } },
+      }),
+    ).toMatchObject({ status: 'rejected', reason: 'not_exposed' })
+
+    expect(await user.prompt(threadId, '[harness-settings] hi')).toBe('Strong.')
+    const [call] = await user.modelCalls()
+    expect(call?.body?.model).toBe('gpt-4.1')
+    const system = (call?.body?.messages ?? [])
+      .filter((message) => message.role === 'system')
+      .map((message) => contentText(message.content))
+      .join('\n')
+    expect(system).toContain('Answer in one word.')
+
+    const described = await user.read('describe', threadId)
+    expect(described.settings).toMatchObject({
+      model: 'strong',
+      instructions: 'Answer in one word.',
+    })
+    expect(described.models).toEqual(expect.arrayContaining(['fast', 'strong']))
+  })
+
+  test('tells the next model call that the working folder changed', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = client(request, testId, aimockPort)
+    const threadId = `cwd-${testId}`
+    // A new thread gets no note, so the note needs a first turn.
+    expect(await user.prompt(threadId, '[harness-cwd] start')).toBe('Started.')
+    expect(
+      await user.control(threadId, {
+        op: 'configure',
+        settings: { cwd: '/repo/app' },
+      }),
+    ).toMatchObject({ status: 'accepted' })
+    expect(await user.prompt(threadId, '[harness-cwd] where')).toBe('Moved.')
+
+    const [, call] = await user.modelCalls()
+    const seen = (call?.body?.messages ?? [])
+      .filter((message) => message.role !== 'system')
+      .map((message) => contentText(message.content))
+    expect(seen).toEqual([
+      '[harness-cwd] start',
+      'Started.',
+      'The working folder is now /repo/app. Paths are relative to it.',
+      '[harness-cwd] where',
+    ])
+  })
+
+  test('starts a fresh context with the handoff note after a reset', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = client(request, testId, aimockPort)
+    const threadId = `reset-${testId}`
+    const note = 'Summary: the user asked a first question.'
+    expect(await user.prompt(threadId, '[harness-reset] first')).toBe(
+      'First answer.',
+    )
+    expect(await user.control(threadId, { op: 'reset', note })).toMatchObject({
+      status: 'accepted',
+    })
+    expect(await user.prompt(threadId, '[harness-reset] second')).toBe(
+      'Second answer.',
+    )
+
+    // The model got only the note and the new message.
+    const calls = await user.modelCalls()
+    const last = calls.at(-1)?.body?.messages ?? []
+    const seen = last
+      .filter((message) => message.role !== 'system')
+      .map((message) => contentText(message.content))
+    expect(seen).toEqual([note, '[harness-reset] second'])
+
+    // The transcript keeps every message, with the reset marker.
+    const transcript: Array<Message> = await user.read('transcript', threadId)
+    const texts = transcript.map((message) => contentText(message.content))
+    expect(texts).toContain('[harness-reset] first')
+    expect(texts).toContain('[harness-reset] second')
+    expect(transcript.some((message) => message.metadata?.harness?.reset)).toBe(
+      true,
+    )
+  })
+
+  test('keeps the metadata an app writes when the next turn writes its usage', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = client(request, testId, aimockPort)
+    const threadId = `chips-${testId}`
+    const update = (data: Record<string, unknown>) =>
+      request.post('/api/harness-protocol/sessions', {
+        headers: user.json,
+        data: { op: 'update', threadId, ...data },
+      })
+    expect(await user.prompt(threadId, '[harness-chips] one')).toBe(
+      'Chips one.',
+    )
+
+    const updated = await update({
+      pinned: true,
+      metadata: { chips: ['a.ts'] },
+    })
+    expect(updated.status()).toBe(200)
+    expect(await user.prompt(threadId, '[harness-chips] two')).toBe(
+      'Chips two.',
+    )
+
+    const entry = async () => {
+      const list = await request.get('/api/harness-protocol/sessions', {
+        headers: user.headers,
+      })
+      const { entries } = (await list.json()) as {
+        entries: Array<{ threadId: string }>
+      }
+      return entries.find((item) => item.threadId === threadId)
+    }
+    // The host writes the usage of the turn after the answer streams.
+    await expect.poll(entry).toMatchObject({
+      pinned: true,
+      metadata: { chips: ['a.ts'] },
+      usage: { turns: 2 },
+    })
+    // The harness `metadataSchema` refuses metadata of another shape.
+    const refused = await update({ metadata: { chips: 'a.ts' } })
+    expect(refused.status()).toBe(400)
+    expect(await refused.json()).toMatchObject({ error: 'invalid_metadata' })
+  })
+
+  test('forks a thread at a message and leaves the source as it was', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const user = client(request, testId, aimockPort)
+    const threadId = `fork-${testId}`
+    expect(await user.prompt(threadId, '[harness-fork] one')).toBe('One.')
+    expect(await user.prompt(threadId, '[harness-fork] two')).toBe('Two.')
+    const source: Array<Message> = await user.read('transcript', threadId)
+    const at = source.find((message) => message.role === 'assistant')?.id
+    if (!at) throw new Error('The first answer has no message id.')
+
+    const response = await request.post('/api/harness-protocol/fork', {
+      headers: user.json,
+      data: { threadId, newThreadId: `${threadId}-copy`, at },
+    })
+    expect(response.status()).toBe(200)
+    const { transcript } = (await response.json()) as {
+      transcript: Array<Message>
+    }
+    expect(transcript.map((message) => contentText(message.content))).toEqual([
+      '[harness-fork] one',
+      'One.',
+    ])
+
+    const after: Array<Message> = await user.read('transcript', threadId)
+    expect(after).toHaveLength(source.length)
+    // A fork onto a thread that has messages is refused.
+    const again = await request.post('/api/harness-protocol/fork', {
+      headers: user.json,
+      data: { threadId, newThreadId: `${threadId}-copy`, at },
+    })
+    expect(again.status()).toBe(400)
+  })
+})